GuidesAPI ReferenceChangelogAPI StatusAPI PolicyGusto Security
API Reference

Get pay periods for a company

get
https://api.gusto-demo.com/v1/companies//pay_periods

Pay periods are the foundation of payroll. Compensation, time & attendance, taxes, and expense reports all rely on when they happened.

To begin submitting information for a given payroll, we need to agree on the time period.

By default, this endpoint returns pay periods starting from 6 months ago to the date today. Use the start_date and end_date parameters to change the scope of the response. End dates can be up to 3 months in the future and there is no limit on start dates.

Starting in version 2023-04-01, the eligible_employees attribute was removed from the response. The eligible employees for a payroll are determined by the employee_compensations returned from the PUT /v1/companies/{company_id}/payrolls/{payroll_id}/prepare endpoint.

scope: payrolls:read

Path Params
string
required

The UUID of the company

Query Params
date

Start date (YYYY-MM-DD) for the pay periods range. Defaults to 6 months ago.

date

End date (YYYY-MM-DD) for the pay periods range. Cannot be more than 3 months in the future. Defaults to today.

string
enum

Comma-separated list of payroll types to include (regular, transition). Defaults to regular only.

Allowed:
Headers
string
enum
Defaults to 2026-02-01

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

Allowed:
Responses

Updated about 1 month ago

Language
Credentials
Bearer
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated about 1 month ago