Managing Workers

In Payroll Infrastructure, workers live in your product. They have no Everee account and never sign in to Everee. You create each worker through the API with everything Everee needs to pay them, you keep that record up to date, and you show them their pay.

Everee calculates pay and taxes, pays the worker, and handles tax filings and year-end forms.

Before you add workers

Set up the company first: work locations, payroll calendars and approval groups. A worker's default work location and payroll calendar are set when you create them. See Setting up the company.

Create a worker

1. Check their hiring status

Before you create anyone, look up their hiring status. A duplicate profile causes payroll and tax filing problems.

2. Send a complete record

In Payroll Infrastructure, every worker is created with a complete record. Embedded onboarding and hosted onboarding are for hosted payroll, because they need the worker to onboard in Everee.

Set onboardingComplete to true. Your workers can't finish onboarding themselves in Everee, so leave nothing for them to do.

POST /integration/v1/workers/employee
{
  "externalWorkerId": "emp-1042",
  "firstName": "Ana",
  "lastName": "Reyes",
  "taxpayerIdentifier": "123456789",
  "dateOfBirth": "1994-05-17",
  "email": "[email protected]",
  "phoneNumber": "8015550142",
  "homeAddress": { "line1": "250 W Center St", "city": "Provo", "state": "UT", "postalCode": "84601" },
  "legalWorkAddress": { "useHomeAddress": false, "workLocationId": 1234 },
  "hireDate": "2026-11-16",
  "payType": "HOURLY",
  "payRate": { "amount": "22.50", "currency": "USD" },
  "typicalWeeklyHours": 40,
  "payrollCalendarId": "17",
  "socCode": "53-3032",
  "bankAccount": { "accountName": "Ana Reyes", "accountType": "CHECKING", "routingNumber": "999000001", "accountNumber": "000123456789" },
  "withholdingSettings": {
    "maritalStatus": "SINGLE_OR_MARRIED_FILING_SEPARATELY",
    "haveExactlyTwoJobs": false,
    "countOfChildren": 0,
    "countOfOtherDependents": 0,
    "otherIncomeAnnually": { "amount": "0.00", "currency": "USD" },
    "deductionsAnnually": { "amount": "0.00", "currency": "USD" },
    "extraWithholdingsMonthly": { "amount": "0.00", "currency": "USD" },
    "exempt": false
  },
  "onboardingComplete": true
}

Store the workerId Everee returns, and send your own ID as externalWorkerId so you can use it in later requests.

What a worker needs to be paid

Two things to know:

• State withholding isn't part of the create request. If the employee's state has income tax, set it with Update state tax withholding settings.
• Everee doesn't capture a W-9 signature. w9FormResponse gives Everee the contractor's tax settings only. If you need a signed W-9 on file, capturing and storing it is up to you.

Field-level detail for every data area is in Onboarding and managing workers.

🔒

You're handling sensitive data

Taxpayer identifiers and bank account numbers pass through your systems. Never log them, and never send them from a client-side request.

What workers don't get in Payroll Infrastructure

Your workers use your product, not Everee. So:

• No Everee account. A worker can't claim an account, set a password or sign in to Everee.
• No invitations. Get Everee access invitation returns 403 for a Payroll Infrastructure company.
• No account setup in components. Everee's worker components are for hosted payroll. If you create a worker component session, accountSetupEnabled is ignored and set to false.
• No pay card. The pay card signup and card management components return 403, so a worker can't get an Everee pay card.
• No messages from Everee. Everee doesn't email or text your workers: no invitations, onboarding reminders, payment notices or rehire messages, whatever the company's notification settings say.

You're responsible for telling workers about their pay, and for anything they need to fix.

How workers are paid

Workers are paid by direct deposit, to the bank account you send. Use the Worker Direct Deposit API to change it later:

The default account gets whatever is left after the splits. If a deposit is returned, see Returned Deposits and Retries.

You pay contractors the same way as employees: add what they're owed to a payroll run. See Running payroll.

Taxes, deductions and leave

Find missing information early

When Everee calculates a worker's payment in a payroll run and something is missing from their record, it opens a requirement. The Requirements API lists it, and it blocks the run until it's fixed. Each one has resolutionInstructions.

These have the sourceDomain WORKER_PROFILE. To list one worker's requirements, send subject-type=WORKER and their externalWorkerId or workerId as subject-id.

Don't wait for payroll day to find them. Add pay to the open run and calculate it early, then check the worker's requirements, especially after you create or change a worker. Subscribe to requirement.created to know when one opens, and requirement.resolved to know when it's fixed. Most resolve on their own once you update the record.

Keep records in sync

Each kind of change has its own endpoint:

To read workers back, retrieve a worker or list workers. These webhook events tell you when something changes:

If you created a worker by mistake, you can delete them only while nothing has been recorded for them, such as pay or deductions.

Separate and rehire

When someone leaves, separate them. You set the separation date and eligibleForRehire, which decides what a later hiring status lookup returns.

A rehire restores the existing profile, so pay and tax history stay with one worker. Its rehireDate can't be earlier than the earliestValidHireDate from the hiring status lookup. If the worker type changes, for example a contractor returning as an employee, create a new worker instead.

What workers see

Workers can't see their pay in Everee, so show it in your product:

See After payroll for telling workers they've been paid, returned deposits and tax forms.