Sign in

v1

latestOpenAPI 3.1.02026-07-243113441.2 MB
Payrolls

Get all payrolls for a company

Returns a list of payrolls for a company. You can change the payrolls returned by updating the processing_status, payroll_types, start_date, & end_date params.

By default, will return processed, regular payrolls for the past 6 months.

Notes:

  • Dollar amounts are returned as string representations of numeric decimals, are represented to the cent.
  • end_date can be at most 3 months in the future and start_date and end_date can't be more than 1 year apart.
  • Results are paginated. Maximum page size is 100 payrolls per request; the default page size is 25.

scope: payrolls:read

get/v1/companies/{company_id}/payrolls

Path parameters

company_idstring required

The UUID of the company

Query parameters

processing_statusesstring[]

Whether to include processed and/or unprocessed payrolls in the response, defaults to processed, for multiple attributes comma separate the values, i.e. ?processing_statuses=processed,unprocessed

payroll_typesstring[]

Whether to include regular and/or off_cycle payrolls in the response, defaults to regular, for multiple attributes comma separate the values, i.e. ?payroll_types=regular,off_cycle

processedboolean

Whether to return processed or unprocessed payrolls

include_off_cycleboolean

Whether to include off cycle payrolls in the response

includestring[]

Include the requested attribute in the response, for multiple attributes comma separate the values, i.e. ?include=benefits,deductions,taxes

start_datestring

Return payrolls whose pay period is after the start date

end_datestring

Return payrolls whose pay period is before the end date. If left empty, defaults to today's date.

date_filter_by'check_date'

Specifies which date field to use when filtering payrolls with start_date and end_date. This field applies only to regular processed payrolls and defaults to pay period if not provided.

pageinteger

The page that is requested. When unspecified, will load all objects unless endpoint forces pagination.

perinteger

Number of objects per page. For majority of endpoints will default to 25

sort_order'asc' | 'desc'

A string indicating whether to sort resulting events in ascending (asc) or descending (desc) chronological order. Events are sorted by their timestamp. Defaults to asc if left empty.

Headers

X-Gusto-API-Version'2026-06-15'

Determines the date-based API version associated with your API call. If none is provided, your application's minimum API version is used.

Response

Successful

payroll_deadlinestring date-time

A timestamp that is the deadline for the payroll to be run in order for employees to be paid on time. If payroll has not been run by the deadline, a prepare request will update both the check date and deadline to reflect the soonest employees can be paid and the deadline by which the payroll must be run in order for said check date to be met.

check_datestring

The date on which employees will be paid for the payroll.

processedboolean

Whether or not the payroll has been successfully processed. Note that processed payrolls cannot be updated. Additionally, a payroll is not guaranteed to be processed just because the payroll deadline has passed. Late payrolls are not uncommon. Conversely, users may choose to run payroll before the payroll deadline.

processed_datestring nullable

The date at which the payroll was processed. Null if the payroll isn't processed yet.

calculated_atstring date-time nullable

A timestamp of the last valid payroll calculation. Null if there isn't a valid calculation.

uuidstring

The UUID of the payroll.

payroll_uuidstring

The UUID of the payroll.

company_uuidstring

The UUID of the company for the payroll.

off_cycleboolean

Indicates whether the payroll is an off-cycle payroll

off_cycle_reason'Adhoc' | 'Benefit reversal' | 'Bonus' | 'Correction' | 'Dismissed employee' | 'Hired employee' | 'Wage correction' | 'Tax reconciliation' | 'Reversal' | 'Disability insurance distribution' | 'Transition from old pay schedule' nullable

The off-cycle reason. Only included for off-cycle payrolls.

auto_payrollboolean

Indicates whether the payroll has automatic payroll enabled

externalboolean

Indicates whether the payroll is an external payroll

final_termination_payrollboolean

Indicates whether the payroll is the final payroll for a terminated employee. Only included for off-cycle payrolls.

withholding_pay_period'Every week' | 'Every other week' | 'Twice per month' | 'Monthly' | 'Quarterly' | 'Semiannually' | 'Annually' nullable

The payment schedule tax rate the payroll is based on. Only included for off-cycle payrolls.

skip_regular_deductionsboolean nullable

Block regular deductions and contributions for this payroll. Only included for off-cycle payrolls.

fixed_withholding_rateboolean nullable

Enable taxes to be withheld at the IRS's required rate of 22% for federal income taxes. State income taxes will be taxed at the state's supplemental tax rate. Otherwise, we'll sum the entirety of the employee's wages and withhold taxes on the entire amount at the rate for regular wages. Only included for off-cycle payrolls.

created_atstring date-time

Datetime for when the resource was created.

partner_owned_disbursementboolean nullable

Will money movement for the payroll be performed by the partner rather than by Gusto?