Gusto

Connect & Ingest data from Gusto

Gusto is a cloud-based payroll, benefits, and HR platform for small and medium businesses. The Sling Gusto connector extracts data from the Gusto REST API, supporting company details, employees, jobs, compensations, departments, payroll data, benefits, time-off activities, and contractor payments.

CLI Pro Required: APIs require a CLI Pro token or Platform Plan.

Setup

The following credentials and inputs are accepted:

Secrets:

• client_id (required) -> Your Gusto OAuth2 application Client ID

• client_secret (required) -> Your Gusto OAuth2 application Client Secret

Inputs:

• company_id (required) -> The UUID of your Gusto company. Find it via GET /v1/token_info

• anchor_date (optional) -> The starting date for historical data extraction (default: 1 year ago). Format: YYYY-MM-DD

Authentication

Gusto uses OAuth2 Authorization Code flow. Sling handles the entire flow automatically — on first run, it opens your browser for authorization and stores tokens for future use.

1. Go to the Gusto Developer Portal and create an account

2. Create a new Organization and then a new Application

3. Note your Client ID and Client Secret

4. Set the Redirect URI to http://localhost:4589/callback

5. Configure the connection using the Client ID and Client Secret (see examples below)

On first run, Sling will:

• Open your browser to the Gusto authorization page

• You authorize the application and are redirected back to localhost:4589

• Sling exchanges the code for access and refresh tokens, stored locally

On subsequent runs, Sling automatically refreshes the access token using the stored refresh token — no browser interaction needed.

Sandbox vs Production: By default, the connector uses the Gusto demo/sandbox environment (api.gusto-demo.com). For production, override base_url, token_url, and authorize_url in secrets to point to api.gusto.com.

Finding Your Company ID

After your first successful authorization, find your company UUID:

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "X-Gusto-API-Version: 2025-06-15" \
     https://api.gusto.com/v1/token_info

The response includes a resource.uuid field — that is your company_id.

Using sling conns

sling conns set GUSTO type=api spec=gusto secrets='{ client_id: your_client_id, client_secret: your_client_secret }' inputs='{ company_id: your_company_uuid }'

Environment Variable

See here to learn more about the .env.sling file.

export GUSTO='{ type: api, spec: gusto, secrets: { client_id: "your_client_id", client_secret: "your_client_secret" }, inputs: { company_id: "your_company_uuid" } }'

Sling Env File YAML

See here to learn more about the sling env.yaml file.

connections:
  GUSTO:
    type: api
    spec: gusto
    secrets:
      client_id: "your_client_id"
      client_secret: "your_client_secret"
    inputs:
      company_id: "your_company_uuid"

With anchor date for historical data:

connections:
  GUSTO:
    type: api
    spec: gusto
    secrets:
      client_id: "your_client_id"
      client_secret: "your_client_secret"
    inputs:
      company_id: "your_company_uuid"
      anchor_date: "2023-01-01"

Replication

Here's an example replication configuration to sync Gusto data to a PostgreSQL database:

source: GUSTO
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: gusto.{stream_name}

streams:
  # Company and org structure
  companies:
  locations:
  departments:
  employees:

  # Jobs and compensation
  jobs:
  compensations:

  # Payroll data (incremental)
  pay_schedules:
  pay_periods:
    mode: incremental
  payrolls:
    mode: incremental

  # Benefits
  company_benefits:
  employee_benefits:

  # Time off
  time_off_activities_vacation:
  time_off_activities_sick:

  # Contractor payments (incremental)
  contractor_payments:
    mode: incremental

Endpoints

Company & Organization

Endpoint	Description	Incremental
companies	Company details, settings, and entity info	No
locations	Company office locations and addresses	No
departments	Company departments with assigned employees	No

Employees & Jobs

Endpoint	Description	Incremental
employees	All employees (active, onboarding, terminated)	No
jobs	Employee job records (title, hire date)	No
compensations	Compensation records (pay rate, FLSA status)	No

Payroll

Endpoint	Description	Incremental
pay_schedules	Pay schedule configurations (frequency, anchor dates)	No
pay_periods	Pay periods with payroll association	Yes
payrolls	Processed payrolls with compensation totals	Yes

Benefits & Time Off

Endpoint	Description	Incremental
company_benefits	Benefits configured for the company	No
employee_benefits	Individual employee benefit enrollments	No
time_off_activities_vacation	Vacation time-off balances and activity history	No
time_off_activities_sick	Sick time-off balances and activity history	No

Contractors

Endpoint	Description	Incremental
contractor_payments	Contractor payment records	Yes

To discover available endpoints:

sling conns discover GUSTO

Incremental Sync

The Gusto connector uses date-range-based incremental sync for supported endpoints:

• First run: Fetches records from anchor_date (default: 1 year ago) to present

• Subsequent runs: Only fetches records after the last sync checkpoint

Incremental sync is supported for:

• pay_periods — syncs by end date

• payrolls — syncs by check date

• contractor_payments — syncs by check date

Parent-Child Endpoints

Several endpoints use a queue-based pattern where parent records feed child endpoint iteration:

1. employees populates employee_ids queue, used by:

   • jobs — fetches jobs per employee

   • employee_benefits — fetches benefits per employee

   • time_off_activities_vacation — fetches vacation activity per employee

   • time_off_activities_sick — fetches sick activity per employee

2. jobs populates job_ids queue, used by:

   • compensations — fetches compensations per job

Ensure parent endpoints run before their children in your replication configuration.

API Versioning

The connector uses Gusto API version 2025-06-15. Gusto uses date-based API versioning via the X-Gusto-API-Version header.

Rate Limiting

The connector automatically handles Gusto's rate limits:

• Uses conservative rate limiting (3 requests/second)

• Retries with exponential backoff on 429 (rate limit) responses

• Maximum 5 retry attempts

If you are facing issues connecting, please reach out to us at [email protected], on discord or open a Github Issue here.