# Warp API Docs

> Build apps and integrations with Warp HR and payroll data.

- [Introduction](https://docs.warp.co/index.md): Warp is the employee management platform built for fast-growing companies. The Warp API lets you build apps and integrations using payroll and HR data.
- [Quickstart](https://docs.warp.co/quickstart.md): Make your first request to the Warp API.
- [Authentication](https://docs.warp.co/authentication.md): Learn how to authenticate requests to the Warp API using API keys.
- [Webhooks](https://docs.warp.co/webhooks.md): Receive signed, typed event notifications from Warp using the Standard Webhooks specification.
- [Pagination](https://docs.warp.co/pagination.md): Learn how to paginate through list endpoints in the Warp API using cursor-based pagination.
- [Rate limiting](https://docs.warp.co/rate-limiting.md): Understand Warp API rate limits and how to handle rate limit errors.
- [Errors](https://docs.warp.co/errors.md): Learn about error handling in the Warp API, including error structure and common error types.
- [List Health Plans](https://docs.warp.co/api-reference/benefits/list-health-plans.md): List company health plans. Defaults to active plans. A plan whose effectiveEndDate has elapsed is reported and filtered as terminated.
- [Get Health Plan](https://docs.warp.co/api-reference/benefits/get-health-plan.md): Get a publicly visible company health plan by id.
- [List Retirement Plans](https://docs.warp.co/api-reference/benefits/list-retirement-plans.md): List company retirement plans. Defaults to active plans. A plan whose effectiveEndDate has elapsed is reported and filtered as terminated.
- [Create Retirement Plan](https://docs.warp.co/api-reference/benefits/create-retirement-plan.md): Create a retirement plan for a company on the manual retirement channel.
- [Get Retirement Plan](https://docs.warp.co/api-reference/benefits/get-retirement-plan.md): Get a company retirement plan by id, regardless of status.
- [Update Retirement Plan](https://docs.warp.co/api-reference/benefits/update-retirement-plan.md): Update a retirement plan for a company on the manual retirement channel.
- [List Benefit Deductions](https://docs.warp.co/api-reference/benefits/list-benefit-deductions.md): List current payroll benefit deductions. Defaults to active deductions. A deduction whose effectiveEndDate has elapsed is reported and filtered as terminated.
- [Create Benefit Deduction](https://docs.warp.co/api-reference/benefits/create-benefit-deduction.md): Create a benefit deduction for a worker.
- [Get Benefit Deduction](https://docs.warp.co/api-reference/benefits/get-benefit-deduction.md): Get the current version of a company benefit deduction by id.
- [Update Benefit Deduction](https://docs.warp.co/api-reference/benefits/update-benefit-deduction.md): Update a benefit deduction. The calculation type cannot change.
- [Get company](https://docs.warp.co/api-reference/company/get-company.md): Get the company associated with your API key, including its unmasked EIN. Requires settings read permission or higher. No parameters are required. The response is the company object directly, and unavailable incorporation dates are null.
- [List Fields](https://docs.warp.co/api-reference/custom-fields/list-fields.md): List the custom worker field definitions your API key can read. Each field belongs to a worker-data category; fields whose category your key cannot read are omitted unless the key holds workers:custom_fields.
- [Create Field](https://docs.warp.co/api-reference/custom-fields/create-field.md): Create a custom worker field definition. The field type is immutable after creation. Select and multi_select fields can include their initial options. Access to values derives from the field category; requires the workers:custom_fields permission.
- [Get Field](https://docs.warp.co/api-reference/custom-fields/get-field.md): Get a custom worker field definition, including its select options. Archived options may appear on existing worker values but cannot be newly selected.
- [Update Field](https://docs.warp.co/api-reference/custom-fields/update-field.md): Update a custom worker field definition. The field type cannot be changed; create a new field instead. Requires the workers:custom_fields permission; changing the category, access level, or input source requires the manage level.
- [Archive Field](https://docs.warp.co/api-reference/custom-fields/archive-field.md): Archive a custom worker field. Archived fields keep their existing worker values but cannot receive new ones. Requires the workers:custom_fields permission at the manage level.
- [Create Field Option](https://docs.warp.co/api-reference/custom-fields/create-field-option.md): Add an option to a select or multi_select custom worker field. The option value should be treated as stable; the label can change. Requires the workers:custom_fields permission.
- [Update Field Option](https://docs.warp.co/api-reference/custom-fields/update-field-option.md): Update the label or sort order of a custom worker field option. Options of archived fields cannot be edited. Requires the workers:custom_fields permission.
- [Delete Unused Field Option](https://docs.warp.co/api-reference/custom-fields/delete-unused-field-option.md): Delete a custom worker field option that is not applied to any worker. Options in use must be archived instead. Requires the workers:custom_fields permission at the manage level.
- [Archive Field Option](https://docs.warp.co/api-reference/custom-fields/archive-field-option.md): Archive a custom worker field option. Archived options remain on existing worker values but cannot be newly selected. Requires the workers:custom_fields permission at the manage level.
- [List Field Values](https://docs.warp.co/api-reference/custom-fields/list-field-values.md): List custom field values for workers, optionally filtered by worker or field. Values are returned only for fields whose category your API key can read.
- [Set Field Value](https://docs.warp.co/api-reference/custom-fields/set-field-value.md): Create or replace a worker's value for a custom field. The value shape must match the field type, and your API key must hold write on the field's category.
- [Clear Field Value](https://docs.warp.co/api-reference/custom-fields/clear-field-value.md): Remove a worker's value for a custom field. Your API key must hold write on the field's category.
- [List Departments](https://docs.warp.co/api-reference/departments/list-departments.md): List all departments for your company.
- [Create Department](https://docs.warp.co/api-reference/departments/create-department.md): Create a new department.
- [Update Department](https://docs.warp.co/api-reference/departments/update-department.md): Update an existing department.
- [List I-9 verifications](https://docs.warp.co/api-reference/i-9-verifications/list-i-9-verifications.md): List current and retained company I-9 verifications in all workflow states, newest first. The API key must have workers profile and compliance read scope.
- [Get I-9 verification](https://docs.warp.co/api-reference/i-9-verifications/get-i-9-verification.md): Get a specific I-9 verification by its id. The API key must have workers profile and compliance read scope.
- [List bank accounts](https://docs.warp.co/api-reference/bank-accounts/list-bank-accounts.md): List stored worker bank accounts, newest first. Requires workers banking and profile read scopes.
- [Get bank account](https://docs.warp.co/api-reference/bank-accounts/get-bank-account.md): Get a stored worker bank account. Requires workers banking and profile read scopes.
- [List Job Levels](https://docs.warp.co/api-reference/levels/list-job-levels.md): List the active standard job levels available to your company.
- [List Offers](https://docs.warp.co/api-reference/offers/list-offers.md): List the candidate offers for your company.
- [Create Offer](https://docs.warp.co/api-reference/offers/create-offer.md): Create and send a candidate offer. The candidate receives an email with a link to the offer portal.
- [Void Offer](https://docs.warp.co/api-reference/offers/void-offer.md): Void a previously sent offer. Only sent offers can be voided.
- [Extend Offer Deadline](https://docs.warp.co/api-reference/offers/extend-offer-deadline.md): Extend the expiration deadline of a sent offer.
- [Resend Offer](https://docs.warp.co/api-reference/offers/resend-offer.md): Resend the offer email to the candidate for a sent offer.
- [Offer Created](https://docs.warp.co/webhooks/offer-created.md): Sent when an offer is created.
- [Offer Signature Requested](https://docs.warp.co/webhooks/offer-signature-requested.md): Sent when a designated employer signer is asked to directly sign a draft offer.
- [Offer Sent](https://docs.warp.co/webhooks/offer-sent.md): Sent when an offer is delivered to a candidate.
- [Offer Viewed](https://docs.warp.co/webhooks/offer-viewed.md): Sent when a candidate views their offer.
- [Offer Accepted](https://docs.warp.co/webhooks/offer-accepted.md): Sent when a candidate accepts their offer.
- [Offer Voided](https://docs.warp.co/webhooks/offer-voided.md): Sent when an offer is voided. Contains an offer snapshot captured when it was voided, including the reason and any notes.
- [Offer Expired](https://docs.warp.co/webhooks/offer-expired.md): Sent when a sent offer reaches its expiration deadline. Contains an offer snapshot with status expired and its expirationTime. Does not emit offer.voided.
- [List Pay Rates](https://docs.warp.co/api-reference/pay-rates/list-pay-rates.md): List pay rates visible to the API key. Results may be filtered by worker, effective start date, or regular/additional type. US and global worker rates require their corresponding compensation read scopes.
- [Get Pay Rate](https://docs.warp.co/api-reference/pay-rates/get-pay-rate.md): Get a specific pay rate by id. The API key must have the compensation read scope corresponding to the worker.
- [Create Regular Pay Rate](https://docs.warp.co/api-reference/pay-rates/create-regular-pay-rate.md): Create an effective-dated regular pay rate for a worker. The API key must have the compensation write scope corresponding to the worker classification. Fixed rates require a nonnegative integer amount in minor currency units, and writes accept only currencies with exactly two ISO 4217 minor-unit dig…
- [Delete Future Regular Pay Rate](https://docs.warp.co/api-reference/pay-rates/delete-future-regular-pay-rate.md): Delete a regular pay rate or variable-pay boundary identified by worker and effective date. The effective date must be strictly after the current UTC date. The API key must have the compensation write scope corresponding to the worker classification. Deletion reopens the predecessor through the dele…
- [Pay Rate Created](https://docs.warp.co/webhooks/pay-rate-created.md): Sent after a regular pay rate is created. The payload is a metadata-only snapshot and never includes compensation values. `id` is null for variable pay because no fixed row is stored; otherwise it can be fetched from the Pay Rates API with the corresponding compensation read scope. Replacing a fixed…
- [Pay Rate Deleted](https://docs.warp.co/webhooks/pay-rate-deleted.md): Sent after a future regular pay rate or variable-pay boundary is deleted. The frozen metadata-only snapshot never includes compensation values. `id` is null for a variable-pay boundary, and a non-null deleted id is no longer fetchable; use `workerId` and `effectiveDate` to identify the change.
- [List pay splits](https://docs.warp.co/api-reference/pay-splits/list-pay-splits.md): List stored pay-split configurations, newest first. Defaults to active. Requires workers banking and profile read scopes plus the applicable US or global compensation read scope.
- [Get pay split](https://docs.warp.co/api-reference/pay-splits/get-pay-split.md): Get a stored pay-split configuration, including retained inactive configurations. Requires workers banking and profile read scopes plus the applicable US or global compensation read scope.
- [List Payrolls](https://docs.warp.co/api-reference/payroll/list-payrolls.md): List payroll summaries newest first with stable cursor ordering. Every amount in totals is expressed in fundingCurrency, the currency the employer uses to fund the payroll. Line-derived categories are converted and rounded per paycheck before aggregation, while netPay remains provider-authoritative.…
- [Get Payroll](https://docs.warp.co/api-reference/payroll/get-payroll.md): Get a payroll by id. Every amount in totals is expressed in fundingCurrency, the currency the employer uses to fund the payroll. Line-derived categories are converted and rounded per paycheck before aggregation, while netPay remains provider-authoritative. Missing, foreign, unauthorized, or unavaila…
- [List Paychecks](https://docs.warp.co/api-reference/payroll/list-paychecks.md): List per-worker paycheck summaries newest first with stable cursor ordering. By default, the response includes every worker type visible to the API key, including US W-2 employees, US 1099 contractors, and global contractors; use workerTypes to narrow the results. Payroll type visibility follows the…
- [Get Paycheck](https://docs.warp.co/api-reference/payroll/get-paycheck.md): Get a paycheck by id. All worker types use the same paycheck schema. Categories that do not apply to a worker are represented by zero-valued totals and empty line-item arrays. For example, a US 1099 contractor with no applicable payroll taxes returns zero `workerTaxes` and `employerTaxes` totals and…
- [List Time Off Policies](https://docs.warp.co/api-reference/time-off/list-time-off-policies.md): Get the time off policies for your company
- [Get Time Off Policy](https://docs.warp.co/api-reference/time-off/get-time-off-policy.md): Get a specific time off policy by id
- [List Time Off Assignments](https://docs.warp.co/api-reference/time-off/list-time-off-assignments.md): Time off assignments are mappings between workers and time off policies. Useful for finding out which policies a worker is assigned to, or which workers are assigned to a given policy.
- [List Time Off Balances](https://docs.warp.co/api-reference/time-off/list-time-off-balances.md): Get worker remaining time-off balances.
- [List Time Off Requests](https://docs.warp.co/api-reference/time-off/list-time-off-requests.md): Get the time off requests that workers in your company have made.
- [Time Off Request Created](https://docs.warp.co/webhooks/time-off-request-created.md): Sent when a worker submits a new time off request.
- [Time Off Request Reviewed](https://docs.warp.co/webhooks/time-off-request-reviewed.md): Sent when a time off request is approved or denied.
- [Time Off Request Deleted](https://docs.warp.co/webhooks/time-off-request-deleted.md): Sent when a time off request is deleted. Carries a snapshot of the request as it existed before deletion.
- [Time Off Balance Adjusted](https://docs.warp.co/webhooks/time-off-balance-adjusted.md): Sent when a worker's time off balance is adjusted.
- [Get Worker](https://docs.warp.co/api-reference/workers/get-worker.md): Get a specific worker by ID.
- [Update Worker](https://docs.warp.co/api-reference/workers/update-worker.md): Update a worker and return the updated worker object. Omitted fields remain unchanged. Requires workers:profile write, plus read access to any referenced department, level, or workplace. See individual fields for update restrictions.
- [Delete Worker](https://docs.warp.co/api-reference/workers/delete-worker.md): Delete a worker. Only workers who have not yet completed onboarding can be deleted. Active workers must be properly offboarded.
- [Reveal Worker SSNs](https://docs.warp.co/api-reference/workers/reveal-worker-ssns.md): Reveal full Social Security numbers for up to 50 workers. Requires the workers:pii read scope. Results preserve request order and use null when a worker has no SSN on file. The request fails if any worker is not found, emits one audit event per worker, and returns Cache-Control: private, no-store.
- [List Workers](https://docs.warp.co/api-reference/workers/list-workers.md): List all workers. Workers include anyone employed by the company, whether US or international, full-time employees or contractors.
- [Create Employee](https://docs.warp.co/api-reference/workers/create-employee.md): 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.
- [Create Contractor](https://docs.warp.co/api-reference/workers/create-contractor.md): Create a new contractor. The worker will be created in draft status and must be invited separately via the invite endpoint. For business contractors, the businessName field is required.
- [Invite Worker](https://docs.warp.co/api-reference/workers/invite-worker.md): Send or resend the worker invite so they can accept and complete onboarding to Warp. If the worker has already been invited, the invite will be resent with extended validity.
- [Worker Created](https://docs.warp.co/webhooks/worker-created.md): Sent when a new worker is created.
- [Worker Updated](https://docs.warp.co/webhooks/worker-updated.md): Sent when a worker's details change.
- [Worker Deleted](https://docs.warp.co/webhooks/worker-deleted.md): Sent when a worker is deleted.
- [Worker Invite Sent](https://docs.warp.co/webhooks/worker-invite-sent.md): Sent when a worker is invited to the platform.
- [Worker Invite Accepted](https://docs.warp.co/webhooks/worker-invite-accepted.md): Sent when a worker accepts their invitation.
- [Worker Onboarding Completed](https://docs.warp.co/webhooks/worker-onboarding-completed.md): Sent when a worker completes onboarding.
- [Worker Offboarding Started](https://docs.warp.co/webhooks/worker-offboarding-started.md): Sent when offboarding begins for a worker.
- [Worker Offboarded](https://docs.warp.co/webhooks/worker-offboarded.md): Sent when a worker has been offboarded.
- [Worker Reactivated](https://docs.warp.co/webhooks/worker-reactivated.md): Sent when a previously offboarded worker is reactivated.
- [List Workplaces](https://docs.warp.co/api-reference/workplaces/list-workplaces.md): List all workplaces for your company.
- [Create Workplace](https://docs.warp.co/api-reference/workplaces/create-workplace.md): Create a new workplace.
- [Update Workplace](https://docs.warp.co/api-reference/workplaces/update-workplace.md): Update an existing workplace.
- [SDKs](https://docs.warp.co/sdks/index.md): Official client libraries for building on the Warp API.
- [TypeScript](https://docs.warp.co/sdks/typescript.md): Build on the Warp API from Node.js, the browser, or any fetch-capable runtime with the warp-hr TypeScript SDK.
- [Go](https://docs.warp.co/sdks/go.md): Build on the Warp API from any Go 1.22+ program with the warp-go-sdk client.

## OpenAPI Specs

- [warp-api@0.0](https://registry.scalar.com/@warp/apis/warp-api@0.0.1?variant=processed&format=json)