The Gusto settings object

The Gusto settings object describes the account’s active Gusto connection and its sync configuration.

Each sync_reminder contains:

A position is one of:

When no reminder has been stored, enabled is false and every other field is null.

The user mapping object

A user mapping links one Harvest teammate to one Gusto person, so tracked time is synced under the teammate’s Gusto profile.

Required permissions

Managing Gusto settings and user mappings requires permission to write company settings. Callers without it receive a 403 Forbidden status code with Not authorized!.

The Gusto integration must be enabled for the account. Accounts without it receive a 403 Forbidden status code with Gusto integration is not enabled for this account.

Every request must include OAuth2 bearer, personal access token, or basic auth credentials and a User-Agent header. Requests with a body require a JSON Content-Type.

Reading settings and deleting a user mapping do not require an active Gusto connection. Updating settings, creating a user mapping, and bulk creating user mappings do; without one they return 409.

Retrieve Gusto settings

Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes Harvest-Api-Stability: beta.

Returns the account’s Gusto settings object and a 200 OK response code.

GET /v2/integrations/gusto/settings

This request takes no parameters.

Example Request:

curl "https://api.harvestapp.com/v2/integrations/gusto/settings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
  "connected": true,
  "needs_reconnect": false,
  "gusto_company_name": "Acme Design",
  "workweek_anchor": "Sunday",
  "workweek_anchor_editable": true,
  "sync_reminder": {
    "enabled": true,
    "frequency": "weekly",
    "weekday": "Monday",
    "monthly_position": null,
    "semimonthly_position_one": null,
    "semimonthly_position_two": null
  },
  "user_mappings": [
    {
      "id": 7001,
      "user_id": 1782959,
      "gusto_entity_type": "Employee",
      "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"
    }
  ]
}

Update Gusto settings

Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes Harvest-Api-Stability: beta.

Updates the FLSA workweek anchor and the sync-reminder schedule. Returns the updated Gusto settings object and a 200 OK response code.

PATCH /v2/integrations/gusto/settings

A missing frequency when sync_reminder.enabled is true returns 422 with sync_reminder.frequency is required when sync_reminder.enabled is true. A missing weekday when sync_reminder.frequency is weekly returns 422 with sync_reminder.weekday is required when sync_reminder.frequency is weekly.

Cadence fields are validated even when sync_reminder.enabled is false; an incomplete cadence returns 422. A complete cadence with enabled false is stored. Setting {"enabled": false} clears the cadence, and fields that belong to another frequency are cleared when the frequency changes.

Updating settings without an active Gusto connection returns 409 with Connect Gusto before changing Gusto settings. Changing the workweek anchor while a time-sheet sync is queued or running returns 409 with A sync is in progress — try again in a moment.

Example Request:

curl -X PATCH "https://api.harvestapp.com/v2/integrations/gusto/settings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"workweek_anchor": "Sunday", "sync_reminder": {"enabled": true, "frequency": "weekly", "weekday": "Monday"}}'

Example Response:

{
  "connected": true,
  "needs_reconnect": false,
  "gusto_company_name": "Acme Design",
  "workweek_anchor": "Sunday",
  "workweek_anchor_editable": true,
  "sync_reminder": {
    "enabled": true,
    "frequency": "weekly",
    "weekday": "Monday",
    "monthly_position": null,
    "semimonthly_position_one": null,
    "semimonthly_position_two": null
  },
  "user_mappings": [
    {
      "id": 7001,
      "user_id": 1782959,
      "gusto_entity_type": "Employee",
      "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"
    }
  ]
}

Create a user mapping

Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes Harvest-Api-Stability: beta.

Links a teammate to a Gusto person. Returns a user mapping object and a 201 Created response code. No Location header is returned; a user mapping has no single-link read.

POST /v2/integrations/gusto/user_mappings

user_id accepts a JSON integer or a string of decimal digits. A non-member teammate, a teammate who is already linked, a Gusto person that is already linked, or a teammate whose time is synced under another profile returns 422.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/integrations/gusto/user_mappings" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"user_id": 1782959, "gusto_entity_type": "Employee", "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"}'

Example Response:

{
  "id": 7001,
  "user_id": 1782959,
  "gusto_entity_type": "Employee",
  "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"
}

Bulk create user mappings

Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes Harvest-Api-Stability: beta.

Links several teammates to Gusto people in one request. Returns a 200 OK response code. Each mapping is created on its own, so a request can succeed partially.

POST /v2/integrations/gusto/user_mappings/bulk_create

A malformed array element returns an indexed 422. The response contains a created_count, a created array of user mapping objects, and a failed array of objects with the user_id that failed and a message.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/integrations/gusto/user_mappings/bulk_create" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"mappings": [{"user_id": 1782959, "gusto_entity_type": "Employee", "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"}, {"user_id": 1782960, "gusto_entity_type": "Contractor", "gusto_entity_uuid": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f8091a"}]}'

Example Response:

{
  "created_count": 2,
  "created": [
    {
      "id": 7001,
      "user_id": 1782959,
      "gusto_entity_type": "Employee",
      "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"
    },
    {
      "id": 7002,
      "user_id": 1782960,
      "gusto_entity_type": "Contractor",
      "gusto_entity_uuid": "2b3c4d5e-6f70-8192-a3b4-c5d6e7f8091a"
    }
  ],
  "failed": []
}

Delete a user mapping

Beta endpoint. Fully available, but the response shape may still change. Until it is frozen, every response includes Harvest-Api-Stability: beta.

Unlinks a teammate from their Gusto person. Returns the deleted user mapping object and a 200 OK response code.

DELETE /v2/integrations/gusto/user_mappings/{USER_MAPPING_ID}

This request takes no body.

Example Request:

curl -X DELETE "https://api.harvestapp.com/v2/integrations/gusto/user_mappings/7001" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "User-Agent: MyApp ([email protected])"

Example Response:

{
  "id": 7001,
  "user_id": 1782959,
  "gusto_entity_type": "Employee",
  "gusto_entity_uuid": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809"
}

Errors

The Gusto settings and user mapping endpoints return the following status codes: