---
title: "Create contractor for embedded onboarding"
method: POST
path: "/integration/v1/embedded/workers/contractor"
---

# Create contractor for embedded onboarding

`POST /integration/v1/embedded/workers/contractor`

## Request

- Base URL: `https://api.everee.com`
- URL: `https://api.everee.com/integration/v1/embedded/workers/contractor`
- Auth: API key in header `Authorization`

The rest of the contractor’s information will be captured during the embedded onboarding process. Note that this operation will designate the worker as a 1099-issued contractor without a formal employment relationship.

## Request body

- object
  - `firstName` string, required
  - `middleName` string
  - `lastName` string, required
  - `phoneNumber` string, required: 10 digits
  - `email` string, required: email format
  - `startDate` string, date, required: ISO8601 date
  - `homeAddress` object, required
    - `line1` string, required
    - `line2` string
    - `city` string, required
    - `state` string, required: two-letter ISO-3166:2 code (like "CA")
    - `postalCode` string, required: 5-digit postal code
  - `externalWorkerId` string
  - `approvalGroupId` integer: The group to assign this contractor to.
  - `w9FormResponse` object: The contractor's Form W-9 information, used to verify their taxpayer identification number (TIN) with the IRS. It supplies tax settings only: Everee doesn't capture a signature, and treats the W-9 as complete.
    - `entityIndividualName` string, required
    - `businessName` string
    - `taxClassification` 'INDIVIDUAL' | 'S_CORP' | 'C_CORP' | 'PARTNERSHIP' | 'TRUST' | 'LLC' | 'OTHER', required
    - `llcTaxClassification` 'S_CORP' | 'C_CORP' | 'PARTNERSHIP': Required if "taxClassification" is "LLC".
    - `socialSecurityNumber` string: 9 digits. Either "socialSecurityNumber" or "employerIdentificationNumber" is required.
    - `employerIdentificationNumber` string: 9 digits. Either "socialSecurityNumber" or "employerIdentificationNumber" is required.
    - `exemptPayeeCode` string
    - `exemptFromFATCAReportingCode` string
    - `effectiveDate` string, date

## Response `201`

201

- Worker: The Worker data structure. Fields that have not been recorded yet (for example while a worker is still onboarding) are returned as null or omitted. This is the same structure returned by every endpoint that responds with a worker.
  - `id` string: The worker's identifier: your external worker ID if one has been set, otherwise Everee's generated worker ID. Use this value in the `{id}` path parameter of worker endpoints.
  - `firstName` string
  - `middleName` string
  - `lastName` string
  - `phoneNumber` string: 10 digits
  - `email` string: email format
  - `onboardingComplete` boolean
  - `hireDate` string, date: ISO8601 date
  - `terminationDate` string, date: ISO8601 date. Only present once the worker has been separated.
  - `dateOfBirth` string, date: ISO8601 date
  - `taxpayerIdentifier` string: 9-digit numeric string (no hyphens or other characters)
  - `tinVerificationStatus` 'NEEDS_VERIFICATION' | 'SENT_FOR_VERIFICATION' | 'VERIFIED' | 'VERIFICATION_FAILED' | 'UNABLE_TO_VERIFY': "NEEDS_VERIFICATION": TIN is pending verification "SENT_FOR_VERIFICATION": TIN has been submitted for verification "VERIFIED": TIN was verified successfully "VERIFICATION_FAILED": TIN failed verification and requires update "UNABLE_TO_VERIFY": TIN could not be submitted for verification
  - `typicalWeeklyHours` integer: integer in range 1-40 inclusive (employees only)
  - `preferredPaymentMethod` 'DIRECT_DEPOSIT' | 'PAY_CARD': "DIRECT_DEPOSIT": worker is paid via ACH to a bank account "PAY_CARD": worker is paid on an Everee-managed pay card
  - `approvalGroup` object: The worker's approval group, if assigned.
    - `id` string
    - `name` string
  - `documentGroups` string[]: Names of the company document groups assigned to the worker.
  - `position` object: The worker's current position and compensation.
    - `payType` 'HOURLY' | 'SALARY': one of: "HOURLY", "SALARY"
    - `payRate` WorkerMoney: A monetary amount.
      - `amount` string: decimal number with format "d+.dd"
      - `currency` string: ISO4217 currency code
    - `title` string
    - `workersCompClassCode` string: The worker's compensation class code, if assigned.
    - `costCenters` object[]: The worker's default cost centers, each as a type key and value.
      - `type` string: The cost center type key.
      - `value` string: The cost center value within that type.
  - `homeAddress` object: The worker's current home address.
    - `line1` string
    - `line2` string
    - `city` string
    - `state` string: 2-letter state abbreviation
    - `postalCode` string: 5-digit ZIP code
  - `bankAccounts` object[]
    - `bankName` string: The bank's name, determined from `routingNumber` and formatted as the Federal Reserve publishes it, for example `BANK OF AMERICA, N.A.`. Read-only: it can't be set.
    - `accountName` string
    - `accountType` 'CHECKING' | 'SAVINGS': one of: "CHECKING", "SAVINGS"
    - `routingNumber` string: 9 digits
    - `accountNumberLast4` string: last 4 digits of the account number
  - `withholdingSettings` object: The worker's current federal W-4 withholding settings.
    - `haveExactlyTwoJobs` boolean
    - `countOfChildren` integer
    - `countOfOtherDependents` integer
    - `otherIncomeAnnually` WorkerMoney: A monetary amount.
      - `amount` string: decimal number with format "d+.dd"
      - `currency` string: ISO4217 currency code
    - `deductionsAnnually` WorkerMoney: A monetary amount.
      - `amount` string: decimal number with format "d+.dd"
      - `currency` string: ISO4217 currency code
    - `extraWithholdingAmount` WorkerMoney: A monetary amount.
      - `amount` string: decimal number with format "d+.dd"
      - `currency` string: ISO4217 currency code
    - `exempt` boolean
    - `maritalStatus` 'HEAD_OF_HOUSEHOLD' | 'MARRIED_FILING_JOINTLY' | 'SINGLE_OR_MARRIED_FILING_SEPARATELY'
  - `legalWorkAddress` object: The worker's current legal work location.
    - `useHomeAddress` boolean
    - `name` string: The name of the work location.
    - `workLocationId` string: The company work location's ID. Omitted if `useHomeAddress` is true.
    - `address` object
      - `line1` string
      - `line2` string
      - `city` string
      - `state` string: 2-letter state abbreviation
      - `postalCode` string: 5-digit ZIP code

## Other responses

- `400`: The request can't be applied. For example: `payeeType` isn't a valid value, or a `documentGroups` entry doesn't match an active document group.
- `422`: An ID field isn't a numeric string. For example: `approvalGroupId`, `timeOffPolicyId`, `workLocationId`, or `stateUnemploymentTaxLocationId` is `abc`.

---

[API](https://skmtc.dev/everee/apis/everee-embed.md) - [All operations](https://skmtc.dev/everee/apis/everee-embed/llms.txt) - [OpenAPI document](https://skmtc.dev/everee/apis/everee-embed/revisions/7b4f6f4912d4?raw)