HRMS
Gusto HR
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. |