Skip to main content

Gusto Component

Manage payroll, benefits, and human resource within Gusto

Component key: gusto ·
· Changelog ↓

Description​

Gusto is a company that provides a cloud-based payroll, benefits, and human resource management software for businesses based in the United States.

Connections​

OAuth 2.0​

key: gustoOauth

To create an OAuth 2.0 app for Gusto, sign up for a Gusto developer account and create a new application.

For detailed information, refer to the Gusto Developer Documentation.

Prerequisites​

Setup Steps​

  1. Log in to the Gusto Developer Portal and create a new application
  2. Enter a name and description for the application
  3. Under Redirect URI, add the OAuth callback URL: https://oauth2.prismatic.io/callback
  4. Save the application configuration

Configure the Connection​

  • Copy the Client ID and Secret from the application settings in the Gusto Developer Portal
  • Enter the Client ID and Client Secret into the connection configuration

Production Access​

Gusto restricts new app integrations to a demo environment until the app has been reviewed and approved for production access. This two-stage process evaluates the integration's security practices and intended use before granting access to real employee and payroll data.

Gusto apps pass through two states before they are ready for deployment.

Demo environment (before production access): Users can authenticate and the OAuth flow completes normally, but the integration connects to api.gusto-demo.com. Only demo payroll data is accessible. No real employee records, company data, or live payroll information can be reached. This is the expected state during development and testing.

Production (after approval): The integration connects to api.gusto.com. Real Gusto accounts and live payroll data become accessible.

Complete the production access process before deploying to end users. Gusto apps begin in the demo environment (api.gusto-demo.com) and can only access demo data. They cannot connect to real Gusto accounts until production access is granted. To gain production access, the integration must complete a two-stage approval process.

Production Pre-Approval​

Submit a production access request through the Gusto Developer Portal. Gusto reviews the request and typically responds within 1–2 weeks, evaluating the integration's intended use case and data access requirements.

Security Review​

In addition to the production access request, Gusto requires a security review. The integration must demonstrate compliance with industry security standards. Acceptable certifications include:

  • SOC 2 Type II
  • ISO 27001

Submit documentation demonstrating compliance as part of the production access process.

Once both the pre-approval and security review are complete, Gusto provides production credentials. Update the connection configuration with the production Client ID and Client Secret to connect to live Gusto accounts (api.gusto.com).

InputNotesExample
Authorize URL

The OAuth 2.0 Authorization URL for Gusto

https://api.gusto.com/oauth/authorize
Client ID

Client Identifier of your app for the API

Client ID
Client Secret

Client Secret of your app for the API

Client Secret
Scopes

Scopes are not used for Gusto

Token URL

The OAuth 2.0 Token URL for Gusto

https://api.gusto.com/oauth/token

Triggers​

Webhook​

Receive and validate webhook requests from Gusto for webhooks you configure. | key: gustoWebhookTrigger

InputNotesExample
Connection

A Gusto webhook subscription can be configured to send event notifications to a flow's webhook URL when resources change in a Gusto account (an "Employee" is created, a "Payroll" is paid, etc.).

How It Works​

When a webhook subscription is first created, Gusto sends a verification request containing a verification_token to the webhook endpoint. This request is routed to the URL Validation branch beneath the trigger. The trigger automatically handles the verification by calling the Gusto API to confirm the token, then responds with the token in the response body.

All subsequent webhook event notifications are routed to the Notification branch.

Configuration​

The trigger requires an OAuth 2.0 connection to authenticate with the Gusto API for webhook verification.

To set up a webhook subscription:

  1. Deploy the instance so the flow's webhook URL is available.
  2. Use the Create Webhook Subscription action (or the Gusto API directly) to create a subscription, providing the flow's webhook URL and the desired subscription types.
  3. Gusto sends a verification request to the webhook URL, which the trigger handles automatically.
  4. Once verified, the subscription becomes active and event notifications begin flowing to the Notification branch.

Event Types​

Available Subscription Types and Events (21 categories)
Subscription TypeEvents
BankAccountcreated, updated, deleted
Companyprovisioned, deprovisioned, partner_authorized, migrated, updated, onboarded, approved, needs_approval, marked_as_high_risk_business, marked_as_marijuana_business, suspended, unsuspended, payroll_transfer_completed
CompanyBenefitcreated, updated, deleted
Contractorcreated, updated, onboarded, deactivated, reactivated, deleted
ContractorPaymentcreated, cancelled
ContractorPaymentGroupcreated, cancelled
Documentcreated, updated, signed
Employeecreated, updated, onboarded, marked_for_self_onboarding, terminated, rehired, deleted, invited_to_partner_portal
EmployeeBenefitcreated, updated, deleted
EmployeeJobCompensationcreated, updated, deleted
ExternalPayrollcreated, updated, deleted
FastAchConfigactivated, deactivated
Formcreated, updated, signed
GeneratedDocumentgenerated, failed
HomeAddresscreated, updated, deleted
Locationcreated, updated
Notificationscreated, resolved
Payrollcreated, updated, calculated, submitted, processed, paid, reversed, partially_reversed, cancelled, processing_failed
PaySchedulecreated, updated
Signatorycreated, updated, deleted, marked_for_invite
WorkAddresscreated, updated, deleted

Refer to the Gusto Webhook Events documentation for the complete and up-to-date list of event types.

Returned Data​

Example Payload
{
  "uuid": "evt_abc123-def456",
  "event_type": "payroll.paid",
  "resource_type": "Company",
  "entity_type": "Payroll",
  "entity_uuid": "pay_xyz789",
  "timestamp": 1705312200,
  "partner_uuid": "partner_abc123",
  "company_uuid": "company_def456"
}

Notes​

  • A single API request may generate multiple webhook events.
  • Gusto retries delivery up to 16 times over 3 days if the endpoint does not return a 2xx response within 10 seconds.
  • Gusto computes an HMAC-SHA256 signature of the event payload using the verification_token as the secret. The signature is sent in the X-Gusto-Signature header and can be used to validate that events originate from Gusto.

Data Sources​

Select Company​

A picklist of companies in your Gusto account. | key: selectCompany | type: picklist

InputNotesExample
Connection
Example Payload for Select Company⤓
Loading…

Select Employee​

A picklist of employees for the selected company. | key: selectEmployee | type: picklist

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Example Payload for Select Employee⤓
Loading…

Select Pay Schedule​

A picklist of pay schedules for the selected company. | key: selectPaySchedule | type: picklist

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Example Payload for Select Pay Schedule⤓
Loading…

Actions​

Create Employee​

Create an employee of a company | key: createEmployee

InputNotesExample
Additional Fields

Additional fields that might not be covered by the standard inputs.

{
  "preferred_first_name": "John"
}
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Date of Birth

The employee's date of birth.

1990-12-30
Email Address

The employee's personal email address. Required if Self Onboarding is true.

john.doe@example.com
First Name

The employee's first name.

Last Name

The employee's last name.

Middle Initial

The employee's middle initial.

Self Onboarding

If true, employee is expected to self-onboard. If false, payroll admin is expected to enter in the employee's onboarding information.

false
Social Security Number

The employee's social security number.

123-45-6789
Example Payload for Create Employee⤓
Loading…

Create Webhook Subscription​

Creates a Webhook Subscription to receive notifications when entities change for Gusto. | key: createWebhookSubscription

InputNotesExample
Connection
Subscription Types

Types of notifications to receive when entities change. Enter as comma-separated values.

type1,type2
Webhook URL

The URL for the webhook subscription.

https://example.com/webhooks
Example Payload for Create Webhook Subscription⤓
Loading…

Delete Webhook Subscription​

Deletes the Webhook Subscription associated with the provided UUID for Gusto. | key: deleteWebhookSubscription

InputNotesExample
Connection
Webhook Subscription UUID

The webhook subscription UUID.

00000000-0000-0000-0000-000000000000
Example Payload for Delete Webhook Subscription⤓
Loading…

Find Employee by Email​

Get an employee by personal email address. | key: findEmployeeByEmail

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Email Address

The employee's personal email address.

john.doe@example.com
Example Payload for Find Employee by Email⤓
Loading…

Get Company by ID​

Get company metadata by ID | key: getCompany

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Example Payload for Get Company by ID⤓
Loading…

Get Employee​

Get an employee by ID | key: getEmployee

InputNotesExample
Connection
Employee ID

A UUID representing a employee.

00000000-0000-0000-0000-000000000000
Example Payload for Get Employee⤓
Loading…

Get Pay Schedule by ID​

Get a pay schedules for a company by pay schedule ID | key: getPaySchedule

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Pay Schedule ID

A UUID representing a pay schedule.

00000000-0000-0000-0000-000000000000
Example Payload for Get Pay Schedule by ID⤓
Loading…

Get Webhook Events​

Get webhook events based on the partner application's scopes for Gusto. | key: getWebhookEvents

InputNotesExample
Connection
Event Type

A string containing the exact event name or use a wildcard match to filter for a group of events.

employee.created
Fetch All

When enabled, automatically fetches all pages of results. Pagination inputs are ignored when this is enabled.

false
Limit

Limits the number of objects returned in a single response, between 1 and 100. Defaults to 25.

Resource UUID

The UUID of the company. If not specified, will return all events for all companies.

00000000-0000-0000-0000-000000000000
Sort Order

Sort resulting events in ascending (asc) or descending (desc) chronological order.

Starting After UUID

Serves as a cursor, returns all events occurring after specified UUID (exclusive).

Example Payload for Get Webhook Events⤓
Loading…

Get Webhook Subscription​

Returns the Webhook Subscription associated with the provided UUID for Gusto. | key: getWebhookSubscription

InputNotesExample
Connection
Webhook Subscription UUID

The webhook subscription UUID.

00000000-0000-0000-0000-000000000000
Example Payload for Get Webhook Subscription⤓
Loading…

List Companies​

List all companies that the currently authenticated user is a part of | key: listCompanies

InputNotesExample
Connection
Fetch All

When enabled, automatically fetches all pages of results. Pagination inputs are ignored when this is enabled.

false
Pagination Page

Which page of results to fetch. See Gusto API documentation for more information.

Example Payload for List Companies⤓
Loading…

List Company Admins​

List all admin users at a company | key: listCompanyAdmins

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Fetch All

When enabled, automatically fetches all pages of results. Pagination inputs are ignored when this is enabled.

false
Pagination Page

Which page of results to fetch. See Gusto API documentation for more information.

Example Payload for List Company Admins⤓
Loading…

List Employees​

List employees of a company | key: listEmployees

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Fetch All

When enabled, automatically fetches all pages of results. Pagination inputs are ignored when this is enabled.

false
Pagination Page

Which page of results to fetch. See Gusto API documentation for more information.

Example Payload for List Employees⤓
Loading…

List Pay Schedules​

List pay schedules for a company | key: listPaySchedules

InputNotesExample
Company ID

A UUID representing a company.

00000000-0000-0000-0000-000000000000
Connection
Fetch All

When enabled, automatically fetches all pages of results. Pagination inputs are ignored when this is enabled.

false
Pagination Page

Which page of results to fetch. See Gusto API documentation for more information.

Example Payload for List Pay Schedules⤓
Loading…

List Webhook Subscriptions​

Returns all webhook subscriptions associated with the provided Partner API token for Gusto. | key: listWebhookSubscriptions

InputNotesExample
Connection
Example Payload for List Webhook Subscriptions⤓
Loading…

Raw Request​

Send raw HTTP request to Gusto | key: rawRequest

InputNotesExample
API Version

The API version to use.

2026-02-01
Connection
Data

The HTTP body payload to send to the URL.

{"exampleKey": "Example Data"}
File Data

File Data to be sent as a multipart form upload.

[{key: "example.txt", value: "My File Contents"}]
File Data File Names

File names to apply to the file data inputs. Keys must match the file data keys above.

Form Data

The Form Data to be sent as a multipart form upload.

[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header

A list of headers to send with the request.

User-Agent: curl/7.64.1
Max Retry Count

The maximum number of retries to attempt. Specify 0 for no retries.

0
Method

The HTTP method to use.

Query Parameter

A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.

Response Type

The type of data you expect in the response. You can request json, text, or binary data.

json
Retry On All Errors

If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.

false
Retry Delay (ms)

The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.

0
Timeout

The maximum time that a client will await a response to its request

2000
URL

Input the path only (/provision), The base URL is already included (https://api.gusto.com/v1). For example, to connect to https://api.gusto.com/v1/provision, only /provision is entered in this field.

/provision
Use Exponential Backoff

Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.

false

Terminate Employee​

End an employee's employment | key: terminateEmployee

InputNotesExample
Connection
Employee ID

A UUID representing a employee.

00000000-0000-0000-0000-000000000000
Run Termination Payroll?

Whether to run a termination payroll for the employee.

false
Termination Date

The date the employee was terminated.

2020-12-30
Example Payload for Terminate Employee⤓
Loading…

Update Webhook Subscription​

Updates the Webhook Subscription associated with the provided UUID for Gusto. | key: updateWebhookSubscription

InputNotesExample
Connection
Subscription Types

Types of notifications to receive when entities change. Enter as comma-separated values.

type1,type2
Webhook Subscription UUID

The webhook subscription UUID.

00000000-0000-0000-0000-000000000000
Example Payload for Update Webhook Subscription⤓
Loading…

Changelog​

2026-05-21​

Added Fetch All input to list actions to retrieve all records across pages in a single call:

  • List Companies
  • List Company Admins
  • List Employees
  • List Pay Schedules
  • Get Webhook Events

2026-05-05​

Enhanced employee and webhook capabilities:

  • Updated to Gusto API version 2026-02-01
  • Added Self Onboarding and Additional Fields inputs to Create Employee action
  • Made Email required on Find Employee By Email action
  • Updated Get Webhook Events action to replace deprecated page/per pagination with Resource UUID, Limit, and Sort Order inputs

2026-04-07​

Added trigger documentation

2026-03-31​

Various modernizations and documentation updates

2026-03-16​

Improved input field documentation with formatted URL links for better readability

2026-02-26​

Added inline data sources for employees and pay schedules to enable dynamic dropdown selection

2025-07-16​

Removed deprecated API token connection in favor of OAuth 2.0

2025-07-14​

Added API version support for compatibility with latest Gusto API