---
updatedAt: 2026-10-07T20:42:51.000Z
agentTools:
projectIndex: https://docs.checkhq.com/llms.txt
---
# Create a payroll
Creates a payroll.
> 📘 Regular payroll periods
>
> `period_start` and `period_end` should represent a regular payroll period on a pay frequency that the company selects and communicates to its employees.
Pass `correction` to create a managed replacement payroll and attach it to a draft [correction](https://docs.checkhq.com/reference/the-correction-object) in the same request. This is the managed-payroll counterpart to [Create an external payroll](https://docs.checkhq.com/reference/create-an-external-payroll) with `correction` — use it when the replacement should run through the standard payroll preview and approval flow rather than as historical pay history.
### Replacement payrolls
When `correction` is supplied:
* `payday` must be in the past, on or after the open quarter start, on or after the company's `start_date`, and within the correction's tax year.
* Nested `items` and `contractor_payments` must use `payment_method` `manual`. Replacement payrolls do not disburse net pay.
* The correction must be in `draft`, belong to the same company, and accept managed replacement payrolls.
* The caller must have `correction:write` or `correction:admin` scope.
Any payroll with a `payday` in the past must include `correction`. Payroll responses include `correction` as the ID of the correction this payroll is an operation of, or `null`. On update, `correction` may be included only to restate the payroll's current correction ID; a different value is rejected.
See [Correcting Pay History](https://docs.checkhq.com/docs/correcting-pay-history) for the full void-and-replace workflow.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "check-api",
"version": "2025-01-01"
},
"servers": [
{
"url": "https://sandbox.checkhq.com"
}
],
"components": {
"securitySchemes": {
"sec0": {
"type": "apiKey",
"in": "header",
"name": "Authorization",
"x-bearer-format": "bearer",
"x-default": "YOUR_API_KEY"
}
}
},
"security": [
{
"sec0": []
}
],
"paths": {
"/payrolls": {
"post": {
"summary": "Create a payroll",
"description": "Creates a payroll. Pass `correction` to create a managed replacement payroll and attach it to a draft [correction](https://docs.checkhq.com/reference/the-correction-object) in the same request. A payroll with a `payday` in the past must include `correction`.",
"operationId": "create-payroll",
"parameters": [
{
"name": "include_items",
"in": "query",
"description": "Enable this flag to define `items` directly on this payroll.",
"schema": {
"type": "boolean",
"default": false
}
},
{
"name": "include_contractor_payments",
"in": "query",
"description": "Enable this flag to define `contractor_payments` directly on this payroll.",
"schema": {
"type": "boolean",
"default": false
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"company",
"period_start",
"period_end",
"payday"
],
"properties": {
"company": {
"type": "string",
"description": "ID of the company to run payroll for."
},
"period_start": {
"type": "string",
"description": "The start of the date range that the payroll covers.",
"format": "date"
},
"period_end": {
"type": "string",
"description": "The end of the date range that the payroll covers.",
"format": "date"
},
"payday": {
"type": "string",
"description": "The date on which employees will be paid for the payroll. A `payday` in the past requires `correction`. When `correction` is supplied, `payday` must be in the past, on or after the open quarter start, on or after the company's `start_date`, and within the correction's tax year.",
"format": "date"
},
"processing_period": {
"type": "string",
"description": "The processing period of the payroll.
One of `three_day`, `two_day`, or `one_day`.
The processing period determines the approval deadline of the payroll. For a payroll with a Friday payday, `three_day` will mean the approval deadline is on Tuesday, whereas `two_day` will mean the approval deadline is on Wednesday, and `one_day` will mean the approval deadline is on Thursday.
The possible values for this field are constrained by the processing periods the company is approved for.
Default: `processing_period` of the company"
},
"correction": {
"type": "string",
"description": "ID of the draft [correction](https://docs.checkhq.com/reference/the-correction-object) to attach this payroll to as a replacement when creating the payroll. Returned on payroll responses as the correction this payroll is an operation of, or `null`. On update, may be included only to restate the payroll's current correction ID — a different value is rejected. Omit for ordinary payrolls. When supplied at create, nested `items` and `contractor_payments` must use `payment_method` `manual` — replacement payrolls do not disburse net pay. The correction must be in `draft`, belong to the same company, and accept managed replacement payrolls. Requires `correction:write` or `correction:admin` scope to attach at create."
},
"type": {
"type": "string",
"description": "Indicates whether the payroll is a regular or [off-cycle](https://docs.checkhq.com/docs/off-cycle-payroll) payroll.
One of `regular` or `off_cycle`. Other payroll types, such as `amendment` and `balancing`, are created by Check and can't be set through the API.
Default: `regular`"
},
"pay_frequency": {
"type": "string",
"description": "Frequency by which [employees](https://docs.checkhq.com/reference/the-employee-object) get paid.
One of `weekly`, `biweekly`, `semimonthly`, `monthly`, `quarterly`, or `annually`.
Default: `biweekly`"
},
"funding_payment_method": {
"type": "string",
"description": "Payment method for funding the payroll.
One of `ach`, `wire`, or `parafin`.
`ach` and `wire` can be set when creating or updating a payroll. `parafin` is set by Check when a payroll advance is accepted and cannot be set or changed via the API.
Default: `ach`"
},
"pay_schedule": {
"type": "string",
"description": "ID of the [pay schedule](https://docs.checkhq.com/reference/the-pay-schedule-object) that the payroll relates to."
},
"off_cycle_options": {
"type": "object",
"description": "Additional configuration options controlling `off_cycle` payroll behavior.",
"properties": {
"force_supplemental_withholding": {
"type": "boolean",
"description": "Whether to tax all earnings as supplemental earnings.
Default: `false`"
},
"apply_benefits": {
"type": "boolean",
"description": "Whether to apply [benefit deductions and contributions](https://docs.checkhq.com/reference/the-employee-benefit-object) to the payroll.
Default: `false`"
},
"apply_post_tax_deductions": {
"type": "boolean",
"description": "Whether to apply [post-tax deductions](https://docs.checkhq.com/reference/the-post-tax-deduction-object) to the payroll.
Default: `false`"
}
}
},
"items": {
"type": "array",
"description": "The set of [payroll items](https://docs.checkhq.com/reference/the-payroll-item-object) associated with the payroll. Must set `include_items=true`.",
"items": {
"properties": {
"employee": {
"type": "string"
},
"payment_method": {
"type": "string"
},
"earnings": {
"type": "array",
"items": {
"properties": {
"type": {
"type": "string",
"description": "Type of earning. Can be one of the following earning types in Types of earnings"
},
"workplace": {
"type": "string",
"description": "ID of the workplace where work for this earning was performed"
},
"earning_code": {
"type": "string",
"description": "The earning code id which will be used to aggregate earnings on the paystub"
},
"description": {
"type": "string",
"description": "Readable description of the earning code that will show up on the paystub"
},
"earning_rate": {
"type": "string",
"description": "The earning rate id which will be used to calculate the gross wage. Required if type is “piece”"
},
"amount": {
"type": "string",
"description": "Amount earned for this earning
May be negative, for example to reverse or correct a previously reported earning"
},
"hours": {
"type": "number",
"description": "Number of hours worked for this earning",
"format": "float"
},
"piece_units": {
"type": "number",
"description": "Number of units of work produced. Required if type is “piece”",
"format": "float"
},
"metadata": {
"type": "string",
"description": "Additional loosely structured information to associate with the earning",
"format": "json"
}
},
"required": [
"workplace"
],
"type": "object"
}
},
"reimbursements": {
"type": "array",
"items": {
"properties": {
"amount": {
"type": "string",
"description": "Amount of reimbursement
Must be greater than or equal to 0 on regular payrolls. Negative values are accepted on external payrolls"
},
"description": {
"type": "string",
"description": "Description for the reimbursement that will show up on the paystub"
},
"code": {
"type": "string",
"description": "Unique code to identify the reimbursement that will be used to aggregate reimbursements on the paystub. Recommended to always be included to have explicit groupings on the paystub."
},
"metadata": {
"type": "string",
"description": "Additional loosely structured information to associate with the reimbursement",
"format": "json"
}
},
"required": [
"amount"
],
"type": "object"
}
},
"benefit_overrides": {
"type": "array",
"description": "The set of benefit override objects associated with this payroll item.",
"items": {
"properties": {
"benefit": {
"type": "string",
"description": "ID of the employee benefit that is being overridden for the payroll item"
},
"employee_contribution_amount": {
"type": "string",
"description": "Updated employee contribution amount to use for this payroll only"
},
"company_contribution_amount": {
"type": "string",
"description": "Updated company contribution amount to use for this payroll only"
}
},
"required": [
"benefit"
],
"type": "object"
}
},
"post_tax_deduction_overrides": {
"type": "array",
"description": "The set of post-tax deduction override objects associated with this payroll item.",
"items": {
"properties": {
"post_tax_deduction": {
"type": "string",
"description": "ID of the miscellaneous post-tax deduction that is being overridden."
},
"amount": {
"type": "string",
"description": "Updated deduction amount to use for this payroll only"
}
},
"required": [
"post_tax_deduction",
"amount"
],
"type": "object"
}
},
"tax_overrides": {
"type": "array",
"description": "The set of tax override objects associated with this payroll item.",
"items": {
"properties": {
"tax": {
"type": "string",
"description": "ID of the tax being overridden. Only Federal Income Tax and State Income Taxes are eligible."
},
"amount": {
"type": "string",
"description": "Updated withholding amount to use for this payroll only."
}
},
"required": [
"tax",
"amount"
],
"type": "object"
}
},
"pto_balance_hours": {
"type": "number",
"description": "The employee's remaining PTO hour balance, for display on the paystub",
"format": "float"
},
"sick_balance_hours": {
"type": "number",
"description": "The employee's remaining sick hour balance, for display on the paystub",
"format": "float"
},
"state_covid_sick_balance_hours": {
"type": "number",
"description": "The employee's remaining sick hour balance from state COVID relief bills, for display on the paystub",
"format": "float"
},
"supplemental_tax_calc_method": {
"type": "string",
"description": "Controls the method used by Check to calculate tax on supplemental earnings. May be flat or aggregate"
},
"paper_check_number": {
"type": "string",
"description": "For accounting. The check number associated with any printed checks. Can be updated even after the associated payroll has been approved. See [Get a paper check](https://docs.checkhq.com/reference/get-a-paper-check) for more details."
},
"metadata": {
"type": "string",
"description": "Additional loosely structured information to associate with the payroll item.",
"format": "json"
}
},
"required": [
"employee"
],
"type": "object"
}
},
"contractor_payments": {
"type": "array",
"description": "The set of [contractor payments](https://docs.checkhq.com/reference/the-contractor-payment-object) associated with the payroll. Must set `include_contractor_payments=true`.",
"items": {
"properties": {
"contractor": {
"type": "string",
"description": "The id of the contractor being paid"
},
"payment_method": {
"type": "string",
"description": "The way the contractor will be paid, either “direct_deposit” or \"manual\"",
"default": "\"direct_deposit\""
},
"amount": {
"type": "string",
"description": "The amount the contractor should be paid",
"default": "\"0.00\""
},
"reimbursement_amount": {
"type": "string",
"description": "The amount to reimburse the contractor",
"default": "\"0.00\""
},
"paper_check_number": {
"type": "string",
"description": "For accounting. The check number associated with any printed checks. Can be updated even after the associated payroll has been approved. See Get a paper check for more details."
},
"workplace": {
"type": "string",
"description": "The Workplace ID associated with this payment."
}
},
"required": [
"contractor"
],
"type": "object"
}
},
"metadata": {
"type": "string",
"description": "Additional loosely structured information to associate with the payroll. Values must be string.",
"format": "json"
},
"bank_account": {
"type": "string",
"description": "ID of the [bank account](https://docs.checkhq.com/reference/bank-accounts-1) that will be used to fund the payroll.
Default: `default_bank_account` of the company"
}
}
}
}
}
},
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"examples": {
"Result": {
"value": "{\n \"id\": \"pay_Z26PNMC7Ky1wfFQzVqfF\",\n \"company\": \"com_sx3svU6K8c5ZkSFlOh5p\",\n \"period_start\": \"2019-06-16\",\n \"period_end\": \"2019-06-29\",\n \"approval_deadline\": \"2019-07-02T00:00:00.000000Z\",\n \"approved_at\": \"2019-06-29T18:26:56.848920Z\",\n \"payday\": \"2019-07-05\",\n \"status\": \"paid\",\n \"type\": \"regular\",\n \"pay_frequency\": \"biweekly\",\n \"funding_payment_method\": \"ach\",\n \"processing_period\": \"four_day\", \n \"off_cycle_options\": null,\n \"managed\": true,\n \"totals\": {\n \"employee_gross\": \"961.54\",\n \"employee_reimbursements\": \"0.00\",\n \"employee_taxes\": \"249.23\",\n \"employee_benefits\": \"0.00\",\n \"post_tax_deductions\": \"0.00\",\n \"employee_net\": \"712.31\",\n \"contractor_gross\": \"100.00\",\n \"contractor_reimbursements\": \"15.00\",\n \"contractor_net\": \"115.00\",\n \"company_taxes\": \"73.56\",\n \"company_benefits\": \"0.00\",\n \"liability\": \"1150.10\",\n \"cash_requirement\": \"1150.10\"\n },\n \"items\": [\n {\n \"id\": \"itm_yvmmsVGFxLoBaMIkqzea\",\n \"payroll\": \"pay_Z26PNMC7Ky1wfFQzVqfF\",\n \"employee\": \"emp_zGGp6wYcxAeu1Ng8IA7v\",\n \"payment_method\": \"direct_deposit\",\n \"net_pay\": \"712.31\",\n \"earnings\": [\n {\n \"amount\": \"961.54\",\n \"hours\": 40.0,\n \"type\": \"regular\",\n \"workplace\": \"wrk_cxcG4vjGKcSXZk1fgKai\",\n \"code\": null,\n \"description\": null\n }\n ],\n \"reimbursements\": [],\n \"taxes\": [\n {\n \"tax\": \"tax_I1Z9zqbBGWIbvlZpN2Vq\",\n \"description\": \"New York SDI\",\n \"amount\": \"0.60\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_ImvSF9CTuMdokf0uwx5x\",\n \"description\": \"Employer FICA Tax\",\n \"amount\": \"59.62\",\n \"payer\": \"company\"\n },\n {\n \"tax\": \"tax_yjNkKk061BTipYv7G4Ti\",\n \"description\": \"New York City Tax\",\n \"amount\": \"31.04\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_S1krAkh75RzdWu5J53HA\",\n \"description\": \"New York State Tax\",\n \"amount\": \"44.20\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_UJrIQbtVErbdez0bYTVN\",\n \"description\": \"New York Family Leave Benefits\",\n \"amount\": \"1.47\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_1XHqR9Qf5t18SD2sfYEe\",\n \"description\": \"Medicare\",\n \"amount\": \"13.94\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_8L3JLfsH4X6dp0maBWfW\",\n \"description\": \"Federal Income Tax\",\n \"amount\": \"98.36\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_ibU8cGhC5OlpOjoQFIXV\",\n \"description\": \"FICA\",\n \"amount\": \"59.62\",\n \"payer\": \"employee\"\n },\n {\n \"tax\": \"tax_O3f21hkS1cvHBZTa61BO\",\n \"description\": \"Employer Medicare Tax\",\n \"amount\": \"13.94\",\n \"payer\": \"company\"\n }\n ],\n \"benefits\": [],\n \"benefit_overrides\": [],\n \"post_tax_deductions\": [],\n \"post_tax_deduction_overrides\": [],\n \"warnings\": []\n }\n ],\n \"contractor_payments\": [\n {\n \"contractor\": \"ctr_90QzaH9xPRI7JRLXnRoU\",\n \"payment_method\": \"manual\",\n \"amount\": \"100.00\",\n \"reimbursement_amount\": \"15.00\"\n }\n ],\n \"is_void\": false,\n \"metadata\": {}\n}"
}
},
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "pay_Z26PNMC7Ky1wfFQzVqfF"
},
"company": {
"type": "string",
"example": "com_sx3svU6K8c5ZkSFlOh5p"
},
"period_start": {
"type": "string",
"example": "2019-06-16"
},
"period_end": {
"type": "string",
"example": "2019-06-29"
},
"approval_deadline": {
"type": "string",
"example": "2019-07-02T00:00:00.000000Z"
},
"approved_at": {
"type": "string",
"example": "2019-06-29T18:26:56.848920Z"
},
"payday": {
"type": "string",
"example": "2019-07-05"
},
"status": {
"type": "string",
"example": "paid"
},
"type": {
"type": "string",
"example": "regular"
},
"pay_frequency": {
"type": "string",
"example": "biweekly"
},
"funding_payment_method": {
"type": "string",
"example": "ach"
},
"processing_period": {
"type": "string",
"example": "four_day"
},
"off_cycle_options": {},
"managed": {
"type": "boolean",
"example": true,
"default": true
},
"totals": {
"type": "object",
"properties": {
"employee_gross": {
"type": "string",
"example": "961.54"
},
"employee_reimbursements": {
"type": "string",
"example": "0.00"
},
"employee_taxes": {
"type": "string",
"example": "249.23"
},
"employee_benefits": {
"type": "string",
"example": "0.00"
},
"post_tax_deductions": {
"type": "string",
"example": "0.00"
},
"employee_net": {
"type": "string",
"example": "712.31"
},
"contractor_gross": {
"type": "string",
"example": "100.00"
},
"contractor_reimbursements": {
"type": "string",
"example": "15.00"
},
"contractor_net": {
"type": "string",
"example": "115.00"
},
"company_taxes": {
"type": "string",
"example": "73.56"
},
"company_benefits": {
"type": "string",
"example": "0.00"
},
"liability": {
"type": "string",
"example": "1150.10"
},
"cash_requirement": {
"type": "string",
"example": "1150.10"
}
}
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "itm_yvmmsVGFxLoBaMIkqzea"
},
"payroll": {
"type": "string",
"example": "pay_Z26PNMC7Ky1wfFQzVqfF"
},
"employee": {
"type": "string",
"example": "emp_zGGp6wYcxAeu1Ng8IA7v"
},
"payment_method": {
"type": "string",
"example": "direct_deposit"
},
"net_pay": {
"type": "string",
"example": "712.31"
},
"earnings": {
"type": "array",
"items": {
"type": "object",
"properties": {
"amount": {
"type": "string",
"example": "961.54"
},
"hours": {
"type": "integer",
"example": 40,
"default": 0
},
"type": {
"type": "string",
"example": "regular"
},
"workplace": {
"type": "string",
"example": "wrk_cxcG4vjGKcSXZk1fgKai"
},
"code": {},
"description": {}
}
}
},
"reimbursements": {
"type": "array"
},
"taxes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tax": {
"type": "string",
"example": "tax_I1Z9zqbBGWIbvlZpN2Vq"
},
"description": {
"type": "string",
"example": "New York SDI"
},
"amount": {
"type": "string",
"example": "0.60"
},
"payer": {
"type": "string",
"example": "employee"
}
}
}
},
"benefits": {
"type": "array"
},
"benefit_overrides": {
"type": "array"
},
"post_tax_deductions": {
"type": "array"
},
"post_tax_deduction_overrides": {
"type": "array"
},
"tax_overrides": {
"type": "array"
},
"warnings": {
"type": "array"
}
}
}
},
"contractor_payments": {
"type": "array",
"items": {
"type": "object",
"properties": {
"contractor": {
"type": "string",
"example": "ctr_90QzaH9xPRI7JRLXnRoU"
},
"payment_method": {
"type": "string",
"example": "manual"
},
"amount": {
"type": "string",
"example": "100.00"
},
"reimbursement_amount": {
"type": "string",
"example": "15.00"
}
}
}
},
"correction": {
"type": "string",
"nullable": true,
"description": "ID of the [correction](https://docs.checkhq.com/reference/the-correction-object) this payroll is an operation of. `null` if the payroll is not attached to a correction."
},
"is_void": {
"type": "boolean",
"example": false,
"default": true
},
"metadata": {
"type": "object",
"properties": {}
}
}
}
}
}
}
},
"deprecated": false
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": true,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```