Create a payroll

post

https://sandbox.checkhq.com/payrolls

Creates a payroll.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

📘
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 in the same request. This is the managed-payroll counterpart to 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.

When the Corrections API is enabled for your integration, 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 for the full void-and-replace workflow.

Query Params

include_items

boolean

Defaults to false

Enable this flag to define items directly on this payroll.

include_contractor_payments

boolean

Defaults to false

Enable this flag to define contractor_payments directly on this payroll.

Body Params

company

string

required

ID of the company to run payroll for.

period_start

date

required

The start of the date range that the payroll covers.

period_end

date

required

The end of the date range that the payroll covers.

payday

date

required

The date on which employees will be paid for the payroll. When the Corrections API is enabled for your integration, 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.

processing_period

string

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

string

ID of the draft correction 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

string

Indicates whether the payroll is a regular, off-cycle, or amendment payroll.

One of regular,off_cycle, or amendment.

Default: regular

pay_frequency

string

Frequency by which employees get paid.

One of weekly, biweekly, semimonthly, monthly, quarterly, or annually.

Default: biweekly

funding_payment_method

string

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

string

ID of the pay schedule that the payroll relates to.

off_cycle_options

object

Additional configuration options controlling off_cycle payroll behavior.

items

array of objects

The set of payroll items associated with the payroll. Must set include_items=true.

items

contractor_payments

array of objects

The set of contractor payments associated with the payroll. Must set include_contractor_payments=true.

contractor_payments

metadata

json

Additional loosely structured information to associate with the payroll. Values must be string.

bank_account

string

ID of the bank account that will be used to fund the payroll.

Default: default_bank_account of the company

Response

Language

Credentials

Header

Loading…

Response

Click Try It! to start a request and see the response here! Or choose an example:

application/json

Regular payroll periods

Replacement payrolls

200200