# Rippling

Connecting Rippling gives SureCloud read access to your Rippling workforce's employee records, employment status, department and role data, and app access assignments. SureCloud monitors employee lifecycle events to support joiner-mover-leaver controls — tracking new hires, role changes, and terminations — and cross-references Rippling's app access records to verify that access is provisioned and deprovisioned in line with HR events. This provides continuous, HR-authoritative evidence of who is employed and what access they should hold at any given point.

{% hint style="info" %}
SureCloud connects to Rippling using OAuth 2.0. The OAuth application is pre-registered by SureCloud — you authorise the connection from within SureCloud without needing to create an app in Rippling.
{% endhint %}

## Authentication and setup

{% stepper %}
{% step %}

#### Initiate the connection in SureCloud

In SureCloud, navigate to **Integrations → Rippling → Connect**. SureCloud redirects you to Rippling's OAuth authorisation page.
{% endstep %}

{% step %}

#### Authorise SureCloud in Rippling

Review the requested permissions and click **Authorise**. SureCloud requests the following OAuth scopes:

| Scope                 | Purpose                                                                               |
| --------------------- | ------------------------------------------------------------------------------------- |
| `employee:read`       | Read employee records including personal data, employment status, and start/end dates |
| `department:read`     | Read department and team structure                                                    |
| `employment:read`     | Read employment type, status, and lifecycle event dates                               |
| `app_management:read` | Read app access assignments per employee                                              |
| `custom_field:read`   | Read custom employee fields used for access scoping or compliance metadata            |

{% hint style="warning" %}
The authorising account must be a **Rippling Administrator** or have the **HR** permission role to grant `employee:read` and `employment:read` scopes across all employees. Non-admin accounts can only read their own records.
{% endhint %}
{% endstep %}

{% step %}

#### Confirm the connected company

After authorisation, SureCloud will display the connected Rippling company name. Confirm this matches the expected entity and click **Save Connection**.
{% endstep %}
{% endstepper %}

## Endpoints

| API Call                            | Use Case                                                                          |
| ----------------------------------- | --------------------------------------------------------------------------------- |
| `GET /v1/employees`                 | Enumerate all employees with employment status, start date, and department        |
| `GET /v1/employees/{id}`            | Read full employee record including role, manager, cost centre, and custom fields |
| `GET /v1/employees/{id}/employment` | Read current employment details including termination date and reason             |
| `GET /v1/departments`               | Enumerate departments and their reporting structure                               |
| `GET /v1/employees/{id}/apps`       | Read app access assignments for each employee                                     |
| `GET /v1/custom-fields`             | List custom field definitions used in employee records                            |
| `GET /v1/leave`                     | Read leave records to identify employees on extended absence                      |

## Pagination

The Rippling API uses cursor-based pagination via a `next` field in the response body. SureCloud passes the cursor value as the `cursor` query parameter in successive requests until no `next` cursor is returned.

```json
{
  "data": [
    {
      "id": "abc123",
      "name": "Alice Nguyen",
      "workEmail": "alice@yourcompany.com",
      "employmentStatus": "ACTIVE",
      "startDate": "2022-03-14"
    }
  ],
  "next": "eyJsaW1pdCI6MTAwLCJvZmZzZXQiOjEwMH0="
}
```

SureCloud requests up to 100 records per page.

## Required permissions

The authorising Rippling account must hold an **Administrator** role or a custom role with read access to employee records and app management. Standard employee accounts cannot grant the required scopes.

## Polling frequency

| Data type                               | Collection interval |
| --------------------------------------- | ------------------- |
| Employee records and employment status  | 24 hours            |
| Department and organisational structure | 24 hours            |
| App access assignments                  | 24 hours            |
| Leave records                           | 24 hours            |

## Troubleshooting

<details>

<summary>Some employees are missing from SureCloud's inventory</summary>

By default, SureCloud requests all employees including terminated employees. If recently terminated employees are not appearing, confirm the `employee:read` scope includes access to terminated records. Rippling may filter terminated employees depending on the OAuth scope grant and the authorising account's HR permissions.

In Rippling, confirm the authorising account has the **View Terminated Employees** HR permission in addition to the standard employee read access.

</details>

<details>

<summary>App access assignments are not appearing for some employees</summary>

The `app_management:read` scope is required to read app assignments. If this scope was not granted during the OAuth flow, app data will be absent from SureCloud.

Re-connect the integration via **SureCloud → Integrations → Rippling → Reconnect** to re-authorise with all required scopes. The authorising account must have the **App Management** permission in Rippling to grant this scope.

</details>

<details>

<summary>Termination dates are missing for terminated employees</summary>

Termination dates are returned in the employment detail endpoint (`/v1/employees/{id}/employment`). If termination dates are absent, the `employment:read` scope may not have been granted, or the authorising account may not have access to view termination data in Rippling.

Confirm the `employment:read` scope is included by re-authorising the connection with an Administrator account.

</details>

<details>

<summary>OAuth connection fails after a Rippling administrator account change</summary>

If the Rippling administrator account that authorised the SureCloud connection is deactivated or loses its Administrator role, the OAuth refresh token may be invalidated.

Re-connect the integration using a current active Administrator account via **SureCloud → Integrations → Rippling → Reconnect**.

</details>

<a href="https://developer.rippling.com/documentation/rest/reference" class="button secondary">Rippling API reference</a>


---

# 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/rippling.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.