# Gusto

SureCloud connects to Gusto to retrieve employee records, employment status, and contractor data. This allows SureCloud to monitor joiner, mover, and leaver events — confirming that access provisioning and deprovisioning controls are triggered in line with employment changes, and that Gusto's employee records remain consistent with identity data collected from connected systems.

## Authentication and setup

Gusto supports OAuth 2.0 for partner and third-party integrations. SureCloud connects via the Gusto OAuth flow.

{% hint style="info" %}
SureCloud uses OAuth 2.0 for this integration. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically.
{% endhint %}

{% stepper %}
{% step %}
**Initiate the connection in SureCloud**

Navigate to **SureCloud → Integrations → Gusto → Connect** and click **Authorise with Gusto**. SureCloud will redirect you to the Gusto authorisation page.
{% endstep %}

{% step %}
**Approve access in Gusto**

Log in to Gusto with an Administrator account. Select the company to connect and approve the requested scopes. Click **Authorise**.
{% endstep %}

{% step %}
**Return to SureCloud**

After authorisation, you will be redirected back to SureCloud with the integration status updated to **Connected**. Click **Test Connection** to confirm data is accessible.
{% endstep %}
{% endstepper %}

## Endpoints

| API Call                                     | Use Case                                                                         |
| -------------------------------------------- | -------------------------------------------------------------------------------- |
| `GET /v1/companies`                          | Retrieve company details including the company UUID for subsequent calls         |
| `GET /v1/companies/{company_id}/employees`   | Enumerate all employees including employment status and start/termination dates  |
| `GET /v1/employees/{employee_id}`            | Retrieve individual employee detail including department, job title, and manager |
| `GET /v1/companies/{company_id}/contractors` | Enumerate contractors engaged by the company                                     |
| `GET /v1/companies/{company_id}/departments` | List departments for organisational structure mapping                            |
| `GET /v1/companies/{company_id}/jobs`        | Retrieve job and compensation records for employment verification                |

## Pagination

`GET /v1/companies/{company_id}/employees` returns up to 25 records per page. SureCloud uses the `X-Next-Page` response header value as the `page` parameter in the next request, continuing until no `X-Next-Page` header is returned.

```
GET /v1/companies/{company_id}/employees?per=25&page=2
```

`GET /v1/companies/{company_id}/contractors` uses the same page-based pattern.

## Required permissions / scopes

SureCloud requests the following OAuth scopes from Gusto:

| Scope              | Purpose                                                       |
| ------------------ | ------------------------------------------------------------- |
| `employees:read`   | Access employee records including status and employment dates |
| `contractors:read` | Access contractor records                                     |
| `departments:read` | Read department and organisational structure                  |
| `company:read`     | Access company-level metadata                                 |

No write, payroll processing, or benefits management permissions are requested.

## Polling frequency

| Data Type                              | Interval       |
| -------------------------------------- | -------------- |
| Employee records and employment status | Every 24 hours |
| Contractor records                     | Every 24 hours |
| Department structure                   | Every 24 hours |

## Troubleshooting

<details>

<summary>OAuth authorisation fails or returns a scope error</summary>

Ensure the Gusto account used for authorisation has Administrator-level access to the company. Non-admin accounts may not have permission to authorise third-party integrations. Retry from **SureCloud → Integrations → Gusto → Connect** with an Admin account.

</details>

<details>

<summary>Terminated employees are not appearing in SureCloud</summary>

By default, `GET /v1/companies/{company_id}/employees` returns only active employees. SureCloud explicitly requests all employee statuses including terminated. If terminated employees are missing, check the integration logs in SureCloud for any scope or permission errors on that endpoint. Confirm the authorising account has permission to view terminated employee records in Gusto.

</details>

<details>

<summary>Multi-entity companies — only one company is returning data</summary>

If your organisation has multiple companies registered in Gusto, the OAuth connection is scoped to the company selected during authorisation. To collect data from additional Gusto companies, each requires a separate connection in SureCloud. Contact SureCloud Support to configure multiple Gusto connections.

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/gusto.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.