HRMS

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.
Jobs & Compensations: Read/Write	Create and update job and compensation details during employee onboarding and profile management.
Home Addresses: Read/Write	Create and update employee home addresses as part of onboarding and HR workflows.
Work Addresses: Read/Write	Read company locations and manage employee work addresses during onboarding and profile updates.
Time Off: Read	Retrieve employee time-off activities filtered by type (vacation, sick leave, etc.).
Token Info: Read	Validate the integration's authentication state and retrieve the company UUID required for API operations.

Setup

In your Gusto Developer Portal, create a new application and save the client ID and secret.
In Atomicwork, navigate to Settings > App Store > Gusto.
Click Connect and choose your environment:
- Select Demo for testing
- Select Production for live accounts
Enter the client ID and secret generated earlier.
Click Connect.

Supported workflow actions

Once connected, you can automate the following Gusto actions within your Atomicwork workflows:

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.

Troubleshoot common issues

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.