--- updatedAt: 2026-10-07T20:42:51.000Z agentTools: projectIndex: https://docs.checkhq.com/llms.txt --- # Create an external payroll Creates an external payroll. Pass `correction` to create a replacement external payroll and attach it to a draft [correction](https://docs.checkhq.com/reference/the-correction-object) in the same request. This is the historical-payroll counterpart to [Create a payroll](https://docs.checkhq.com/reference/create-payroll) with `correction` — use it when the replacement should be recorded as pay history outside the managed payroll flow. ### Replacement external payrolls When `correction` is supplied: * The company must have run a managed payroll. * `payday` must be in the past, before the company's `start_date`, and within the correction's tax year. * The correction must be in `draft`, belong to the same company, and accept replacement payrolls. * The caller must have `correction:write` or `correction:admin` scope. Supplying `correction` also allows creating an external payroll replacement for a company that otherwise could not use the external payroll API for that tax year. External 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. External payrolls attached to a correction reject [Validate an external payroll](https://docs.checkhq.com/reference/validate-an-external-payroll), [Approve an external payroll](https://docs.checkhq.com/reference/approve-an-external-payroll), [Reopen an external payroll](https://docs.checkhq.com/reference/reopen-a-pending-payroll), and [Preview an external payroll](https://docs.checkhq.com/reference/preview-an-external-payroll) with error type `payroll_managed_by_correction`. 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": { "/external_payrolls": { "post": { "summary": "Create an external payroll", "description": "Creates an external payroll. Pass `correction` to create a replacement external payroll and attach it to a draft [correction](https://docs.checkhq.com/reference/the-correction-object) in the same request. This is the historical-payroll counterpart to [Create a payroll](https://docs.checkhq.com/reference/create-payroll) with `correction`.", "operationId": "create-an-external-payroll", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "company", "period_start", "period_end", "payday" ], "properties": { "company": { "type": "string", "description": "ID of the company this external payroll is 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 were paid for the payroll. When `correction` is supplied, `payday` must be in the past, before the company's `start_date`, and within the correction's tax year.", "format": "date" }, "pay_frequency": { "type": "string", "description": "Frequency at which the external payroll was paid" }, "correction": { "type": "string", "description": "ID of the draft [correction](https://docs.checkhq.com/reference/the-correction-object) to attach this external payroll to as a replacement when creating the payroll. Returned on external 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 external payrolls. When supplied at create, the company must have run a managed payroll; `payday` must be in the past and before the company's `start_date`; and the correction must be in `draft`, belong to the same company, and accept replacement payrolls. Allows creating an external payroll replacement for a company that otherwise could not use the external payroll API for that tax year. Requires `correction:write` or `correction:admin` scope to attach at create." }, "items": { "type": "array", "description": "The set of [external payroll items](https://docs.checkhq.com/reference/external-payroll-item-object) associated with the payroll.", "items": { "properties": { "employee": { "type": "string", "description": "ID of the employee that was paid" }, "earnings": { "type": "array", "items": { "properties": { "amount": { "type": "string", "description": "Amount paid out on this payroll" }, "hours": { "type": "string", "description": "Hours worked on this payroll" }, "type": { "type": "string", "description": "Earning type, one of [Earning Types](https://docs.checkhq.com/reference/types-of-earnings)" }, "workplace": { "type": "string", "description": "ID of workplace that the earning was worked at" }, "earning_code": { "type": "string", "description": "ID of the custom earning code used for this earning. Either this or `type` must be provided." } }, "type": "object" } }, "reimbursements": { "type": "array", "items": { "properties": { "amount": { "type": "string", "description": "Amount reimbursed" } }, "required": [ "amount" ], "type": "object" } }, "taxes": { "type": "array", "items": { "properties": { "tax": { "type": "string", "description": "ID of the tax paid" }, "amount": { "type": "string", "description": "Amount paid in this tax" } }, "required": [ "tax", "amount" ], "type": "object" } }, "benefits": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "ID of the benefit object that represents this deduction. One of `ID` or `benefit` must be provided." }, "benefit": { "type": "string", "description": "The [benefit type](https://docs.checkhq.com/reference/types-of-benefits) of this deduction. Either `id` or `benefit` must be provided." }, "description": { "type": "string", "description": "Description of the benefit provided. If ID is provided, this field will not take effect and instead be superseded by the benefit object's description." }, "employee_contribution_amount": { "type": "string", "description": "Amount the employee contributed to the benefit for this payroll" }, "company_contribution_amount": { "type": "string", "description": "Amount the company contributed to this benefit for this payroll" } }, "type": "object" } }, "post_tax_deductions": { "type": "array", "items": { "properties": { "id": { "type": "string", "description": "ID of the post-tax deduction deducted from pay. Either this or `description` must be provided." }, "amount": { "type": "string", "description": "Amount deducted from pay" }, "description": { "type": "string", "description": "Description of the post-tax deduction deducted. Either this or `id` must be provided." } }, "type": "object" } } }, "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.", "items": { "properties": { "amount": { "type": "string", "description": "Amount paid to this contractor" }, "reimbursement_amount": { "type": "string", "description": "Amount reimbursed to the contractor" }, "contractor": { "type": "string", "description": "ID of the contractor paid" } }, "type": "object" } }, "metadata": { "type": "string", "description": "Additional loosely structured information to associate with the payroll. Values must be string.", "format": "json" } } } } } }, "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 \"approved_at\": \"2019-06-29T18:26:56.848920Z\",\n \"payday\": \"2019-07-05\",\n \"status\": \"paid\",\n \"pay_frequency\": \"biweekly\",,\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 \"post_tax_deductions\": [],\n }\n ],\n \"contractor_payments\": [\n {\n \"contractor\": \"ctr_90QzaH9xPRI7JRLXnRoU\",\n \"amount\": \"100.00\",\n \"reimbursement_amount\": \"15.00\"\n }\n ],\n}" } } } } } }, "deprecated": false } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true } ```