Onboarding and Managing Workers

This guide walks through the whole life of a worker in Everee: creating them, getting them through onboarding so they can be paid, keeping their data in sync with yours, and rehiring or separating them. Read Setting up your organization first if you haven't created work locations, payroll calendars, or approval groups yet.

Employees and contractors

Every worker is created as either an employee or a contractor. You choose when you create them, and it decides how they're paid, taxed, and reported.

	Employee (W-2)	Contractor (1099)
Taxes	Withheld and remitted for you, along with the employer's share	The contractor is responsible for their own taxes
Tax form collected	W-4 and state forms, plus a Form I-9 if the company's setup calls for one	W-9
Year-end form	W-2	1099
Paid	On a payroll calendar, or as soon as possible	As soon as possible
Hours	Timesheets API	Not tracked by Everee. Send payable items

Everee's tax operations team calculates and remits the taxes, files quarterly and annual forms, and issues W-2 and 1099 forms, so none of it needs to be built into your integration.

Choose how workers get onboarded

📘
Payroll Infrastructure is full record only
In Payroll Infrastructure, workers are created with a full record through the API. The embedded onboarding and hosted onboarding sections on this page apply to hosted payroll.

A worker has to finish onboarding before Everee can pay them. During onboarding they confirm their personal details, taxpayer identifier, bank account or pay card, and tax forms. There are three ways to do it. Integrations typically use embedded onboarding or the full record.

	Embedded onboarding	Full record	Hosted onboarding
Who collects the sensitive data	The worker, in an Everee component inside your app	You, in your own forms	The worker, in Everee
What you send	Basics, including the home address: name, contact info, hire date, pay, work location	Everything: SSN, date of birth, address, bank account, W-4	A few basics: name, contact info, hire date, pay, work location
Where the worker onboards	Your app, in a webview or iframe	Nowhere. The profile is complete when you create it	A branded Everee page, reached by a link
Sensitive data passes through you	No	Yes. You take on the risk and responsibility for it	No
Best for	Platforms with a worker-facing app that want a seamless experience	Platforms that already hold this data, or companies migrating from another payroll system	Platforms with no worker-facing app, or that want the fastest path
Endpoint	Add an employee or contractor for embedded onboarding	Add a complete employee record or contractor record	Kick off onboarding for an employee or contractor

With embedded onboarding and hosted onboarding, Everee collects the sensitive details itself, so you never have to handle tax or banking information.

The worker lifecycle

create worker ──► Onboarding ──► worker completes ──► Active ──► payable
     │                                   │
 worker.created               worker.onboarding-completed

You get a webhook event at each step, so there's no need to poll:

Event	Meaning	What to do
`worker.created`	The worker's profile exists	Store the Everee `workerId` against your own record
`worker.onboarding-completed`	The worker finished onboarding and can be paid	Unlock whatever depends on it in your product, and start sending hours and payables
`worker.tin-verification-status-changed`	The taxpayer identifier did or didn't match IRS or SSA records	On `VERIFICATION_FAILED`, ask the worker to correct their name or TIN. W-2 and 1099 forms can't be filed accurately until it's fixed
`worker.profile-updated`	Something on the profile changed, in Everee or through the API	Retrieve the worker and re-sync your copy

Store the completed state yourself when you receive worker.onboarding-completed. That way you don't have to ask Everee on every page load.

📘
Onboarding doesn't always happen in the worker's hands
Some companies manage all HR and payroll data offline, so their payroll admins (hosted payroll) or your platform (through the API) enter everything a worker would otherwise provide. Those workers never go through onboarding themselves. Their profile is complete as soon as the admin has entered the data.

What makes a worker payable

A worker can be paid once Everee has the data below and the worker has completed onboarding. Who supplies each item depends on how you onboard them. See Choose how workers get onboarded.

Data area	What Everee needs	How it's provided
Identity	Name, date of birth, phone number, and email	Embedded: You send name, phone, and email when you create the worker. The worker provides date of birth in the onboarding component. Full record: You send all four (`dateOfBirth` is required). Hosted: You send name, phone, and email when you kick off onboarding. The worker provides date of birth on the hosted page.
Taxpayer identifier	SSN or other taxpayer identifier. Everee checks it against IRS and SSA records. See `worker.tin-verification-status-changed`	Embedded: The worker enters it in the onboarding component. Full record: You send `taxpayerIdentifier` for an employee, or `socialSecurityNumber` or `employerIdentificationNumber` in `w9FormResponse` for a contractor. Hosted: The worker enters it on the hosted page.
Home address	The worker's residence, used for tax and forms	Embedded: You send `homeAddress` when you create the worker. Full record: You send `homeAddress`. Hosted: The worker enters it on the hosted page.
Work location	The worker's default legal work address	Embedded: You send `legalWorkAddress`. Full record: You send `legalWorkAddress`. Hosted: You send `legalWorkAddress`.
Position and pay	Pay type, pay rate, typical weekly hours, and hire date (contractors have only a start date)	Embedded: You send them on create. Full record: You send them on create. Hosted: You send them when you kick off onboarding.
Payment method	A bank account or pay card, unless the worker is paid outside Everee	Embedded: The worker adds it in the onboarding component. Full record: You send `bankAccount`. Hosted: The worker adds it on the hosted page.
Tax forms	A W-4 and state forms for employees, or a W-9 for contractors	Embedded: The worker completes them in the onboarding component. For a contractor's W-9, see Contractor W-9 options. Full record: You send `withholdingSettings` for an employee, or `w9FormResponse` for a contractor. Hosted: The worker completes them on the hosted page.

To change any of this after the worker exists, see Keeping profiles in sync.

Contractor W-9 options

A contractor's W-9 can be captured in one of two ways, and the two can't be combined.

The contractor completes and signs it. Create the contractor without w9FormResponse. In the onboarding component, the contractor enters their name, tax classification and taxpayer identifier, and signs the W-9.
You send the W-9 information. Include w9FormResponse when you create the contractor. Everee uses it to verify the taxpayer identifier and treats the W-9 as complete. It supplies tax settings only: Everee doesn't capture a signature, and the contractor isn't asked to sign. If you need a signed W-9 on file, capturing and storing it is up to you. The contractor then completes the remaining onboarding steps, such as payment details.

You can't send w9FormResponse and then have the contractor review and sign the W-9 in the onboarding component.

Switching a contractor between an individual and a business

A contractor is an individual or a business according to their W-9, so to switch them after they've been created, send the new W-9 information to Update Form W-9 info. This is how a sole proprietor who forms an LLC, or a business that becomes an individual, is updated.

Send a taxClassification of INDIVIDUAL for an individual, or any other classification for a business, with the name and either an SSN or an EIN. A business must use an EIN.
The change applies as soon as the request succeeds, and Everee checks the taxpayer identifier again.
Read the result back with Get Form W-9 info, which needs a date.
Form 1099. Whichever status is in effect on December 31 is the one used for the values on the contractor's Form 1099 in the filing process.

When the worker finishes everything left for them, Everee sends worker.onboarding-completed and the worker's onboardingComplete is true.

Wages and payables submitted early are held. You can send hours and other wage items for a worker who isn't payable yet. Everee holds them as unpayable. When the worker completes onboarding, they become available for payout.

Before you create a worker: check their hiring status

Whichever approach you use, before creating a profile, look up their hiring status, especially if you're an ATS or you hire people who've worked with the company before. A duplicate profile causes payroll and tax filing problems.

POST https://api.everee.com/integration/v1/worker-hiring-status/search

{
  "taxpayerIdentifier": "123456789",
  "firstName": "Ana",
  "lastName": "Reyes",
  "externalWorkerId": "emp-1042"
}

Send as much data as you have. Social Security number is the most reliable. The response's hiringScenario tells you what to do:

`hiringScenario`	What to do
`NEW_HIRE`	Create a profile
`ACTIVE`	Don't create one. Link the existing worker to your record using the `workerId` in the response
`ELIGIBLE_FOR_REHIRE`	Rehire the worker instead of creating a new profile
`NOT_ELIGIBLE_FOR_REHIRE`	Don't create a profile. The company has marked this person as not eligible

Embedded onboarding

Embedded onboarding follows the lifecycle above, with the worker onboarding inside your product.

1. Create the worker

Use Add an employee or Add a contractor for embedded onboarding.

POST https://api.everee.com/integration/v1/embedded/workers/employee

{
  "externalWorkerId": "emp-1042",
  "firstName": "Ana",
  "lastName": "Reyes",
  "email": "[email protected]",
  "phoneNumber": "8015550142",
  "hireDate": "2026-11-02",
  "payType": "HOURLY",
  "payRate": { "amount": "22.50", "currency": "USD" },
  "typicalWeeklyHours": 40,
  "homeAddress": {
    "line1": "250 W Center St",
    "city": "Provo",
    "state": "UT",
    "postalCode": "84601"
  },
  "legalWorkAddress": { "useHomeAddress": false, "workLocationId": 1234 },
  "approvalGroupId": "56"
}

externalWorkerId is your own identifier for the worker. Send it so you can refer to the worker by your ID in later requests, including when you create component sessions.
legalWorkAddress is the worker's default work location. Pass a workLocationId, or set useHomeAddress to true. It decides which overtime rules apply, and it's the default tax location for hours that don't specify their own.
Optional fields include approvalGroupId (assign it now: it decides who can see and approve the worker, see Approval groups), timeOffPolicyId to enroll them in a leave policy, default costCenters, and socCode.
A contractor takes a startDate instead of a hire date and no pay details. Send w9FormResponse only if you want Everee to treat their W-9 as complete from the information you send. That passes sensitive data through you and captures no signature. Leave it out and the contractor enters and signs their W-9 during onboarding. See Contractor W-9 options.

Store that the worker has been created, along with the workerId Everee returns.

2. Show the onboarding component

Create a component session with experience set to ONBOARDING, and show the returned URL in a webview or iframe. experienceOptions let you control whether the worker sets up an Everee login, shows the welcome and confirmation screens, and more.

3. Listen for completion

When the worker finishes, you get two signals:

A WORKER_ONBOARDING_COMPLETE component event in your client, so your interface can update straight away.
A worker.onboarding-completed webhook event on your server.

Store the completed state when you receive the webhook, so you don't have to ask Everee on every page load. See Embedded Worker Onboarding for the details.

Full record

If you collect everything yourself, send a complete profile with Add a complete employee record or Add a complete contractor record. The request includes the taxpayer identifier, date of birth, home address, bank account, and for employees the W-4 withholding settings.

Set onboardingComplete to true to mark onboarding complete, which moves the worker to Active once their hire date is reached. Leave it false to let the worker finish onboarding themselves, if that's available.

🔒
You're handling sensitive data
With this approach, SSNs and bank account numbers pass through your systems. Make sure your platform is set up to protect them. Never log them, and never put them in a client-side request.

Workers you pay outside Everee

Some workers are paid by another system, but you still want them in Everee for records, tax filings, or reporting. Mark them as externally paid with Update payment preferences:

PUT https://api.everee.com/integration/v1/workers/emp-1042/payment-info

{
  "availablePaymentMethods": {
    "externallyPaid": true
  }
}

The worker's preferredPaymentMethod becomes EXTERNALLY_PAID. You can't set that value directly in preferredPaymentMethod; it only follows from externallyPaid.

Exclusive. externallyPaid can't be combined with directDeposit or payCard. Sending it with either set to true returns an error.
No bank account or pay card needed. Everee doesn't wait for payment details, so the worker can complete onboarding without them.
No money moves. Payments for the worker are recorded in Everee, and Everee doesn't send funds. Make sure you actually pay them elsewhere.
Switching back. To start paying the worker through Everee, send externallyPaid: false with directDeposit or payCard set to true. Everee switches their preferred method and asks them to add their payment details.

Hosted onboarding

With hosted onboarding the worker onboards on a branded Everee page instead of inside your product. It suits platforms without a worker-facing app, and it's the fastest to build.

1. Create the profile

POST https://api.everee.com/integration/v1/workers/onboarding/employee

{
  "workerId": "emp-1042",
  "firstName": "Ana",
  "lastName": "Reyes",
  "email": "[email protected]",
  "phoneNumber": "8015550142",
  "hireDate": "2026-11-02",
  "payType": "HOURLY",
  "payRate": { "amount": "22.50", "currency": "USD" },
  "typicalWeeklyHours": 40,
  "legalWorkAddress": { "workLocationId": "1234" },
  "approvalGroupId": "56",
  "payrollCalendarId": "7"
}

workerId is your own identifier for the worker. Send it so you can find the worker later by your ID. It's returned as id on worker responses.
legalWorkAddress is the worker's default work location. Pass a workLocationId, or set useHomeAddress to true. It decides which overtime rules apply, and it's the default tax location for hours that don't specify their own.
Everything else is optional: approvalGroupId, payrollCalendarId, timeOffPolicyId to enroll them in a leave policy, default costCenters, and documentGroups. If you don't send payrollCalendarId, the worker goes on the company's default calendar.
Contractors take fewer fields: no pay type, rate, or weekly hours. See Kick off onboarding for a contractor.

The worker's status is Onboarding until they finish.

2. Send the worker to onboarding

Get the worker's onboarding link and send it to them:

GET https://api.everee.com/integration/v1/workers/onboarding-access-details?external-worker-id=emp-1042

The hosted onboarding page uses your company's branding.

3. Wait for `worker.onboarding-completed`

Then start paying them. See Sending pay to Everee.

Keeping profiles in sync

Workers can be edited in your platform, by the workers themselves, and (in hosted payroll) in the Everee admin portal. Decide which system is the source of truth for each field.

Matching records. Store your own ID on the worker as externalWorkerId (or workerId when kicking off onboarding), and use it with the hiring status search and the Search for workers endpoint. You can change it later, but anything else that stored the old value may stop matching.

Pushing changes to Everee. Each kind of change has its own endpoint:

Change	Endpoint
Name, email, phone, date of birth	Update personal information
Home address	Update home address
Title, pay rate, pay type, weekly hours, default cost centers	Update position and compensation
Default work location	Update work location
Approval group	Update approval group
Payroll calendar	Update payroll calendar
Payment preferences	Update payment preferences
Bank accounts and splits	Worker Direct Deposit API
Taxpayer identifier	Update taxpayer identifier
Hire date	Update start date

Pulling changes from Everee. Subscribe to worker.profile-updated. It's a catch-all with only the worker's IDs, so when you receive it, retrieve the worker and update your copy. To reconcile everyone at once, list workers, filtering by lifecycle-status or payrollCalendarId.

Separating a worker

When someone leaves, separate them in Everee:

Worker type	Endpoint	Notes
Employee	Separate an employee	You choose the separation date, whether they're eligible for rehire, severance, the benefits end date, and how remaining time off is paid out
Contractor	Separate a contractor

The eligibleForRehire flag you set here is what a later hiring status search returns, so set it deliberately.

Separating a worker triggers worker.profile-updated.

Rehiring a worker

When the hiring status is ELIGIBLE_FOR_REHIRE, restore the existing profile rather than creating a new one:

POST https://api.everee.com/integration/v1/workers/{workerId}/rehire

{
  "rehireDate": "2027-03-01",
  "useHomeAddress": false,
  "workLocationId": "1234",
  "employeePosition": {
    "payType": "HOURLY",
    "payRate": { "amount": "24.00", "currency": "USD" },
    "expectedWeeklyHours": 40
  }
}

The rehireDate can't be earlier than earliestValidHireDate from the hiring status. employeePosition is only required when you're rehiring an employee.

If the worker's type is changing, for example a former contractor returning as an employee, don't rehire. Create a new profile instead.

See Rehire a worker.

Correcting mistakes

Wrong hire date. Update the start date.
Created by mistake. You can delete a worker's profile only while nothing has been recorded under it beyond what onboarding collects. After any shift, payable, deduction, or imported history exists, the request fails.
Duplicate profile. A profile that already has payroll data can't be deleted. Contact [email protected].

If a create or update was rejected and you want to see what Everee received, see Diagnosing a failed request.

Checklist

Look up hiring status before every create.
Store Everee's workerId and send your own ID as the external worker ID.
Subscribe to worker.onboarding-completed and worker.profile-updated before you go live.
Don't expect a worker to be paid until worker.onboarding-completed, unless payroll admins are entering their data directly. Wages you send before then are held until onboarding completes. See What makes a worker payable.
Set a default work location on every worker, even if you set one on each shift.

Employees and contractors

Choose how workers get onboarded

Payroll Infrastructure is full record only

The worker lifecycle

Onboarding doesn't always happen in the worker's hands

What makes a worker payable

Contractor W-9 options

Switching a contractor between an individual and a business

Before you create a worker: check their hiring status

Embedded onboarding

1. Create the worker

2. Show the onboarding component

3. Listen for completion

Full record

You're handling sensitive data

Workers you pay outside Everee

Hosted onboarding

1. Create the profile

2. Send the worker to onboarding

3. Wait for worker.onboarding-completed

Keeping profiles in sync

Separating a worker

Rehiring a worker

Correcting mistakes

Checklist

Next steps

3. Wait for `worker.onboarding-completed`