Gusto v2
Provides integration with Gusto for reading company, employee, compensation, pay-schedule, payroll, and contractor-payment data, managing custom earning types, and preparing and updating unprocessed payrolls.
Revision History
0.1.0.9 - Initial release.
Connection
Use a Gusto Connection to authorize access to a company through the Gusto App Integrations API.
| Property | Type | Description |
|---|---|---|
Environment |
Enum | Select Demo or Production. Defaults to Demo. Token exchange, token refresh, and API requests use the selected environment. |
Client ID |
String | Required OAuth application identifier issued by Gusto. |
Client Secret |
Masked | Required OAuth application secret issued by Gusto. |
Scopes |
String | Required, space-separated OAuth scopes requested during authorization. The default is public companies:read employees:read compensations:read pay_schedules:read payrolls:read payrolls:write. |
Access Token |
Masked | Company access token populated by OAuth authorization. Required for API requests. |
Refresh Token |
Masked | Rotating refresh token populated by OAuth authorization and used to renew the access token. |
Company UUID |
String | Company identifier populated by the Connection test. Used as company_id when that option is omitted. |
Timeout (seconds) |
Integer | Timeout for API and OAuth requests. Defaults to 30 and must be greater than zero. |
Setup Notes
- Obtain the client credentials for your Gusto App Integration in the environment you intend to use.
- Create a Connection for
Gustoand setEnvironment,Client ID,Client Secret, andScopes. - Authorize access to the required Gusto company through OAuth. Authorization populates the tokens and tests the Connection to obtain
Company UUID. - Select the Connection and a Method template on the Node, then replace sample values with your own identifiers, filters, and request data.
Interactive OAuth authorization always uses Gusto's https://api.gusto.com/oauth/authorize endpoint, regardless of the selected Environment.
If you add scopes to your Gusto App Integration after authorizing a company, authorize the company again so that its tokens include the new scopes.
The Connection test reads Gusto token information and requires a company UUID in the response. The Node requests API version 2026-06-15.
The Gusto Node supports the cloud Runtime.
Methods
Select a template for the required operation. The template supplies OperationId and describes the supported Options, request fields, and response fields. An operation must belong to the selected Method.
Query
Reads Gusto data using the following templates.
| Template | Required options |
|---|---|
Get company |
company_id. |
List employees |
company_id. |
Get employee |
employee_id. |
List job compensations |
job_id. |
Get compensation |
compensation_id. |
List pay schedules |
company_id. |
Get pay schedule |
company_id, pay_schedule_id. |
Get pay schedule assignments |
company_id. |
Get pay periods |
company_id. |
List earning types |
company_id. |
List payrolls |
company_id. |
Get payroll |
company_id, payroll_id. |
List contractor payments |
company_id, start_date, end_date. |
Get contractor payment |
company_id, contractor_payment_id. |
For operations that require company_id, you can omit it when the Connection has a Company UUID. Additional filters depend on the selected template.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | Gusto Connection details. |
OperationId |
String | Required operation identifier supplied by the selected template. |
Options |
Object | Route identifiers and supported query filters for the selected operation. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Stream of Gusto records. Payroll detail results contain one payroll object per employee-compensation page. Query rows do not include Flowgear mutation metadata. |
Create
Creates a custom earning type with the Create custom earning type template. Each input item provides one request body.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | Gusto Connection details. |
OperationId |
String | Operation identifier supplied by the template. |
Options |
Object | company_id, which defaults to the Connection's Company UUID when omitted. |
Items |
Array | Structured request bodies for the earning types to create. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Created earning types or handled error responses, with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Update
Renames a custom earning type with Update custom earning type, or updates an unprocessed payroll with Update payroll.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | Gusto Connection details. |
OperationId |
String | Operation identifier supplied by the selected template. |
Options |
Object | company_id and either earning_type_uuid or payroll_id. An omitted company_id defaults to the Connection's Company UUID. |
Items |
Array | Structured update bodies. A payroll body must contain an employee_compensations array with no more than 100 entries. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Updated records or handled error responses, with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Delete
Deactivates a custom earning type with Deactivate custom earning type. This Method sends one request using the identifiers in Options and has no Items parameter.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | Gusto Connection details. |
OperationId |
String | Operation identifier supplied by the template. |
Options |
Object | company_id and earning_type_uuid. An omitted company_id defaults to the Connection's Company UUID. |
| Return | Type | Description |
|---|---|---|
Response |
Array | A result containing Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. A successful deactivation has no Gusto response body. |
Action
Runs Prepare payroll for update or Calculate accruing time-off hours. Preparing a payroll returns the payroll data needed for a versioned update. Calculating accruing time-off hours returns the hours_earned entries for one payroll employee.
| Parameter | Type | Description |
|---|---|---|
Connection |
Connection | Gusto Connection details. |
OperationId |
String | Operation identifier supplied by the selected template. |
Options |
Object | For payroll preparation, supply company_id and payroll_id; sort_by is optional. For time-off calculation, supply payroll_id and employee_id. An omitted company_id defaults to the Connection's Company UUID. |
Items |
Array | Optional structured request bodies. Payroll preparation accepts an employee_uuids array with no more than 100 entries. Omitting Items runs the action without a body; an empty input stream runs no action. |
| Return | Type | Description |
|---|---|---|
Response |
Array | Payroll pages, individual time-off accrual results, or handled error responses, with Flowgear.IsSuccess, Flowgear.Message, and Flowgear.Request. |
Usage Notes
Options and input streams
Use the option names supplied by the template. Names are case-sensitive, and unsupported options are rejected. Supply array-valued filters as arrays; the Node converts them to comma-separated query values. Boolean filters are sent as lowercase true or false.
Options applies to the entire invocation. Each non-null Items entry is a separate request body. Create and Update send no requests when Items is omitted or empty. Null entries are skipped.
The first query page or mutation request completes before the Node returns its response stream. Later pages and input items are processed as the Workflow consumes that stream.
Pagination and response shapes
The Node handles pagination automatically for supported paged operations. Do not add page or per to Options. Employee, job-compensation, pay-schedule, and contractor-payment lists use pages of 25; payroll lists, payroll details, and payroll preparation use pages of 100.
Get payroll and Prepare payroll for update retain the payroll object and its nested employee_compensations array on each page. They do not return individual employee compensation rows. GustoPagination contains the Page, TotalCount, TotalPages, and PerPage values when Gusto supplies the corresponding headers.
List earning types returns the default and custom collections as individual rows, with GustoEarningTypeCategory set to default or custom. List contractor payments returns entries from contractor_payments and copies the collection's total into GustoCollection.Total on each row.
Errors and retries
For Create, Update, Delete, and Action, HTTP 404, 409, and 422 responses become result rows with Flowgear.IsSuccess set to false. Inspect that field before treating a write as successful. Flowgear.Message describes the result, and Flowgear.Request contains the input body or, for a bodyless action, the required route values.
Query failures and other unsuccessful HTTP responses raise errors. The Node allows up to two transient retries for GET requests receiving 429, 502, 503, or 504. Write requests are not retried for those statuses. A 401 response triggers at most one token refresh and retry.