Onboarding and Paying Contractors

This guide walks through the most common contractor integration in hosted payroll from start to finish: you add a 1099 contractor, they onboard, you send Everee the amounts you owe them, and Everee pays them.

In Payroll Infrastructure, contractors are paid the same way as employees: add what they're owed to a payroll run as items, under a contractor pay code. See Running payroll.

Contractors don't have a regular payroll cycle. Nothing is paid until their payables are processed, either because you ask (step 4) or because your company has automatic processing turned on. Missing this step is the most common reason contractors aren't paid.

Before you start

• Webhooks. Subscribe to the events in this guide instead of polling. See Implementing a webhook handler.
• Pay codes. Contractor payments use the CONTRACTOR pay code, or REIMBURSEMENT for expenses you're paying back. To label amounts your own way, create your own pay codes.
• Approval groups, if you use them. See Setting up your organization.

1. Add the contractor

Call Create contractor for embedded onboarding with the basics. The contractor fills in everything else during onboarding.

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

{
  "firstName": "Jordan",
  "lastName": "Rivera",
  "email": "[email protected]",
  "phoneNumber": "8015550142",
  "startDate": "2026-11-09",
  "homeAddress": {
    "line1": "123 Main St",
    "city": "Salt Lake City",
    "state": "UT",
    "postalCode": "84101"
  },
  "externalWorkerId": "contractor-2291"
}

• Set externalWorkerId to your own ID for the contractor. You can then send payables and request payouts using your ID, without storing Everee's.
• Contractors take a startDate, and no pay type, rate, or hours. You send what they're owed as payables.
• The W-9. Leave out w9FormResponse and the contractor enters and signs their W-9 during onboarding. Send it and Everee uses your information instead, treats the W-9 as complete, and captures no signature. See Contractor W-9 options.

If the contractor may already exist in Everee, for example from earlier work with this company, check their hiring status first.

Other ways to create a contractor, such as sending a complete record or a hosted onboarding link, are compared in Choose how workers get onboarded.

2. Get the contractor through onboarding

Create a component session with experience set to ONBOARDING, and show the returned URL in a webview or iframe. The contractor confirms their details, completes their W-9, and adds a bank account or Everee Pay Card. See Embedding Everee components.

When they finish, you get:

Wait for worker.onboarding-completed before you expect a contractor to be paid. Payables you send earlier are held, and become available for payout when the contractor finishes onboarding.

3. Send what the contractor is owed

Each amount is a payable item: one amount, for one contractor, under a pay code.

POST https://api.everee.com/integration/v1/payables

{
  "externalId": "contractor-2291::job-88412",
  "externalWorkerId": "contractor-2291",
  "label": "Job 88412, Nov 6",
  "payableModel": "PRE_CALCULATED",
  "payCode": "CONTRACTOR",
  "type": "job",
  "amount": { "amount": 240.00, "currency": "USD" },
  "earningTimestamp": 1793980800
}

• externalId must be stable and unique. It's how Everee recognizes a retry: send the same externalId again and the payable is updated, not duplicated. Build it from your own records, like a contractor and a job, and never from a timestamp or random value.
• earningTimestamp is when the amount was earned, in Unix seconds.
• To send many at once, use Create payables (bulk). If your company processes payables automatically, send a contractor's items for one payout in a single bulk call.

Payable items aren't taxed for contractors. Everee totals them for the contractor's 1099.

4. Process the payables

Creating payables doesn't pay anyone. They have to be processed into payments. There are two ways to do this, and your company uses one of them.

Requesting payout

Call Request ASAP payout once you've sent everything you want in this payout:

POST https://api.everee.com/integration/v1/payables/payment-request

{}

With no parameters, Everee processes every unpaid payable item of your contractors, and creates one payment per contractor. Employees' items are left for their regular payroll. To limit the request, send externalIds, externalWorkerIds, or workerIds.

The response says what was processed:

{
  "id": 654321,
  "payableCount": 3,
  "payableExternalIds": ["contractor-2291::job-88412", "contractor-2291::job-88415", "contractor-3107::job-88420"],
  "companyId": 10,
  "createdAt": "2026-11-06T20:20:20.000Z"
}

A 200 with payableCount: 0 means nothing was waiting.

Most integrations request payout on a schedule they choose, such as daily or after each job, which decides how often contractors are paid.

• Call it after you've sent all the items for this payout. Items you send afterward wait for the next request.
• Call it before payments are approved, if a payroll admin approves them on a schedule.

Processing payables automatically

Instead of requesting payout, your company can have Everee process each payable as soon as you create it. This is a company setting, auto-process payables for off-cycle workers, that Everee turns on or off for you. It isn't available through the API. Ask your Everee contact whether it's on for your company, or to change it.

With it on:

• Every create request is processed straight away. You don't call Request ASAP payout.
• It applies to workers who aren't on a regular payroll cycle, which includes all contractors.
• Each create request becomes its own payment per contractor. Create three payables one at a time and the contractor gets three payments. To pay them once, send their items together in one bulk request.

5. Approval

Processed payments still wait for approval before money moves. A payroll admin approves them in the Everee admin portal, or they're approved automatically if your company uses auto-approval. Auto-approval is off by default, and Everee can turn it on when you ask. For contractors paid automatically after each job, you'll usually want both.

You can update or delete a payable until its payment is approved. Processing doesn't lock it. After approval, changing or deleting it needs correction-authorized=true. See Changing or removing an amount.

6. Know when the contractor is paid

How soon the money arrives depends on how the contractor is paid: by direct deposit, or instantly to the Everee Pay Card.

To find what hasn't been paid yet, list unpaid payables for a contractor.

After the work ends

• Separate the contractor with Separate a contractor when you stop working with them. See Separating a worker.
• Year end: Everee files and issues each contractor's 1099. Nothing needs to be built into your integration.
• Becoming an employee: a contractor who becomes an employee needs a new employee profile. See Rehiring a worker.

Common mistakes

• Never processing the payables. Without a payout request or automatic processing, contractors' payables wait indefinitely.
• Requesting payout before sending everything. The late items wait for the next request.
• Creating payables one at a time with automatic processing on. Each becomes its own payment.
• A random or time-based externalId. A retry then creates a duplicate, and the contractor is paid twice.
• Expecting payment before onboarding finishes. Payables are held until worker.onboarding-completed.

Next steps

• Sending pay to Everee, for employees and other kinds of earnings
• Onboarding and managing workers
• Guide to the Payables API