The sync run object

A sync run posts Harvest time entries to Gusto for a date range or a Gusto payroll. It is created by creating a sync run and read by retrieving a sync run.

The counts report the run’s latest recorded outcome for each entry.

The sync preview object

A preview reports the entries that a sync run would post, without creating the run.

Each projects entry contains:

suggested_job_uuid is the job already posted for the group, or the only available job, or null.

Required permissions

Managing Gusto sync runs 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.

Retrieving a sync run does not require an active Gusto connection. Previewing and creating one do.

Preview a sync run

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

Previews a time-sheet sync for a date range or a Gusto payroll. Returns a sync preview object and a 200 OK response code. This request does not create a run.

POST /v2/integrations/gusto/sync_runs/preview

A malformed date, a start date after the end date, or a range longer than 90 days returns 422.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/integrations/gusto/sync_runs/preview" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"date_range_start": "2026-10-13", "date_range_end": "2026-10-19"}'

Example Response:

{
  "date_range_start": "2026-10-13",
  "date_range_end": "2026-10-19",
  "gusto_payroll_uuid": null,
  "locked_filtered_count": 0,
  "api_errors": [],
  "projects": [
    {
      "user_mapping_id": 7001,
      "user_id": 1782959,
      "project_id": 14308069,
      "dominant_state": "syncable",
      "entry_count": 3,
      "total_hours": 12.5,
      "state_counts": {
        "syncable": 3,
        "already_synced": 0,
        "edited": 0,
        "deleted_needs_delete": 0,
        "data_error": 0,
        "exempt": 0,
        "owner": 0,
        "contractor_not_hourly": 0,
        "flsa_unverified": 0,
        "flsa_conflict": 0
      },
      "job_required": true,
      "suggested_job_uuid": "9f8e7d6c-5b4a-3928-1706-e5f4d3c2b1a0",
      "available_jobs": [
        {
          "uuid": "9f8e7d6c-5b4a-3928-1706-e5f4d3c2b1a0",
          "title": "Designer"
        }
      ]
    }
  ]
}

Create a sync run

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

Creates and queues a time-sheet sync run for a date range or a Gusto payroll. Returns a sync run object, a 201 Created response code, and a Location header pointing to the run.

POST /v2/integrations/gusto/sync_runs

An invalid date range returns 422. An array element that is not an object, a non-integer user_mapping_id or project_id, or a non-string gusto_job_uuid returns an indexed 422. Pairs that are not eligible in the range, or have no entries left to sync, return one 422 listing every such pair. A missing gusto_job_uuid where one is required returns 422 with Pick a Gusto Job for every selected project. A gusto_job_uuid is not checked against the pair’s available jobs when the run is created: an unknown job is accepted, and its entries are reported as skipped when the run processes them. Creating a run while another run is active returns 409 with A Gusto time-sync run is already in progress.

Example Request:

curl -X POST "https://api.harvestapp.com/v2/integrations/gusto/sync_runs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Harvest-Account-Id: $ACCOUNT_ID" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyApp ([email protected])" \
  -d '{"date_range_start": "2026-10-13", "date_range_end": "2026-10-19", "projects": [{"user_mapping_id": 7001, "project_id": 14308069, "gusto_job_uuid": "9f8e7d6c-5b4a-3928-1706-e5f4d3c2b1a0"}]}'

Example Response:

{
  "id": 4201,
  "status": "queued",
  "run_type": "time_sheet",
  "date_range_start": "2026-10-13",
  "date_range_end": "2026-10-19",
  "gusto_payroll_uuid": null,
  "workweek_anchor": "Sunday",
  "initiated_by_user_id": 1782884,
  "created_at": "2026-10-19T14:30:00Z",
  "started_at": null,
  "completed_at": null,
  "terminal_error_message": null,
  "created_count": 0,
  "skipped_count": 0,
  "error_count": 0
}

Retrieve a sync run

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

Retrieves an existing sync run. Returns a sync run object and a 200 OK response code.

GET /v2/integrations/gusto/sync_runs/{SYNC_RUN_ID}

This request takes no parameters.

Example Request:

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

Example Response:

{
  "id": 4201,
  "status": "completed",
  "run_type": "time_sheet",
  "date_range_start": "2026-10-13",
  "date_range_end": "2026-10-19",
  "gusto_payroll_uuid": null,
  "workweek_anchor": "Sunday",
  "initiated_by_user_id": 1782884,
  "created_at": "2026-10-19T14:30:00Z",
  "started_at": "2026-10-19T14:30:05Z",
  "completed_at": "2026-10-19T14:30:41Z",
  "terminal_error_message": null,
  "created_count": 3,
  "skipped_count": 0,
  "error_count": 0
}

Errors

The Gusto sync run endpoints return the following status codes: