Gusto HR

Gusto HR: Overview and setup

Configure the Gusto HR integration to automate employee lifecycle workflows.

Connect Gusto to Atomicwork to automate employee onboarding, manage time-off tracking, and keep employee profiles in sync across your HR and IT workflows.

Usecases

By connecting Gusto, your teams can:

Automate employee onboarding: Create employee records with home address, work address, job, and compensation details as part of onboarding workflows.
Keep employee profiles in sync: Read and update employee information — including addresses, jobs, and compensation — to ensure Atomicwork always reflects the latest HR data.
Track time-off activity: Pull time-off records filtered by type (vacation, sick leave, etc.) for visibility into employee leave.
Self-service HR queries: Employees can ask Atom about their profile, time-off balance, or employment details.
Custom API operations: Execute generic API calls to any Gusto endpoint for use cases beyond the standard actions.

Permissions

To connect Gusto to Atomicwork, you need:

Org admin access in Atomicwork
An active Gusto Developer Portal account with permission to configure OAuth 2.0 applications

Permission	Purpose
Employees: Read/Write	List, create, retrieve, and update employee records.
Company Info: Read	Retrieve company-level information, including the company UUID used for all company-scoped operations and company locations for work address assignment.

Action	Description
List employees	List all employees in the company with pagination and search.
Create employee	Create a new employee with optional nested entities — home address, work address, job, and compensation. If a nested entity fails, the employee is still created and the response includes warnings for the failed entities.
Get employee	Retrieve detailed employee information including current home address and all compensations.
Update employee	Update employee information with optional nested updates to addresses, job, and compensation.
Get employee time-off activities	Retrieve time-off activities for an employee, filtered by type.
Call API	Execute a generic API call to any Gusto endpoint for custom operations.

Error	Cause	Resolution
Authentication failure	Environment field doesn't match your Gusto account (Demo vs. Production). Demo uses `api.gusto-demo.com`, Production uses `api.gusto.com`.	Verify the environment selected during setup matches where your Gusto account lives.
Token refresh failure	The refresh token has expired or been revoked.	Re-authenticate the integration from Settings > App Store > Gusto.
4xx error during token exchange	The authorization code has expired or the redirect URI doesn't match the configured value.	Re-initiate the OAuth flow from Settings > App Store > Gusto.
Update employee failure (409 Conflict)	Gusto uses version strings to prevent conflicting updates. Another process updated the resource between the read and write.	Retry the operation. The new request will fetch the updated version string automatically.
Partial employee creation	The employee record was created, but a nested entity (address, job, or compensation) failed. The response includes warnings listing the failed entities.	Use the Update employee action to add the missing entities to the existing record.
Action failure — not found or invalid data	The target employee wasn't found, required fields are missing, or the data provided is invalid.	Verify the employee exists and that all required fields are correctly populated.

Gusto HR

Gusto HR

Gusto HR: Overview and setup

Usecases

Permissions

Gusto HR

Gusto HR

Gusto HR: Overview and setup

Usecases

Permissions

Setup

Supported workflow actions

Troubleshoot common issues