Sign in

v20

latestOpenAPI 3.1.0raw.githubusercontent.com2026-03-271727149.6 KB
Workers

Create a new US employee. The worker will be created in draft status and must be invited separately via the invite endpoint. If hiring in a state without an existing tax registration, you must specify the stateRegistration field.

post/v1/workers/employee

Request body

firstNamestring required

a string with no leading or trailing whitespace

lastNamestring required

a string with no leading or trailing whitespace

positionstring required

a string with no leading or trailing whitespace

startDatestring required

A date string in the form YYYY-MM-DD

emailstring required

Personal email address. The invite will be sent here.

workEmailstring nullable

An email with a reasonably valid regex (shamelessly taken from zod)

requireI9boolean

Whether the employee is required to complete I-9 work authorization. Set to false if the employee has already been verified off-platform. Defaults to true.

stateRegistration'self_managed' | 'warp_managed'

How state tax registration is handled for this employee's work state. Required when hiring in a state where your company doesn't have an existing registration. Use 'self_managed' if you've already registered in this state, or 'warp_managed' for Warp to handle registration on your behalf.

departmentIdstring required

The department to assign this employee to.

managerIdstring required

The worker id of this employee's direct manager.

stockOptionsnumber nullable

a non-negative number

paySchedule'weekly' | 'biweekly' | 'monthly' | 'semimonthly' | 'quarterly' | 'annually' nullable

The employee's pay schedule. Must be a pay schedule that the company has configured.

Example request

{
  "startDate": "2000-01-01",
  "email": "john@joinwarp.com",
  "workEmail": "john@joinwarp.com",
  "departmentId": "dpt_1234",
  "managerId": "wrk_1234",
  "stockOptions": 10000,
  "workLocation": {
    "workplaceId": "wkp_1234"
  }
}

Response

Success

idstring required

The id of the worker.

positionstring required
type'employee' | 'contractor' required
status'draft' | 'invited' | 'onboarding' | 'active' | 'offboarding' | 'inactive' required
startDatestring required

A date string in the form YYYY-MM-DD

endDatestring nullable required

A date string in the form YYYY-MM-DD

isBusinessboolean nullable required
businessNamestring nullable required
firstNamestring required
lastNamestring required
emailstring required

An email with a reasonably valid regex (shamelessly taken from zod)

workEmailstring nullable required

An email with a reasonably valid regex (shamelessly taken from zod)

preferredNamestring nullable required
displayNamestring required

The "ui" name of a worker. If it's a business contractor business name is used. Otherwise we default to preferred name, then first-last.

timeZonestring nullable required

The IANA timezone of the worker (e.g., America/New_York).

Example response

{
  "id": "wrk_1234",
  "position": "Research Engineer",
  "startDate": "2000-01-01",
  "endDate": "2000-01-01",
  "firstName": "Jonathan",
  "lastName": "Galt",
  "email": "john@joinwarp.com",
  "workEmail": "john@joinwarp.com",
  "preferredName": "John",
  "displayName": "Jack Galt",
  "timeZone": "America/New_York",
  "department": {
    "id": "dpt_1234",
    "name": "Engineering"
  }
}