Source: https://manu-tests-all-orgs.docs-staging.pageloop.ai/integrations/hrms/gusto-hr # 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](https://docs.gusto.com/embedded-payroll/docs/quickstart) 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. | ---