> ## Documentation Index
> Fetch the complete documentation index at: https://docs.humanintelligence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rippling

> Integrate HR, payroll, and IT system data for unified people and operational intelligence.

Rippling uses **API tokens** to authenticate requests. Each token inherits the permission profile of the user who created it, and you select exactly which data scopes the token can access at creation time. This guide walks through generating a token with the scopes required for the Human Intelligence integration.

If you want Human Intelligence to also sync payroll data, Rippling gates payroll endpoints behind a **separate scope set** that must be requested from Rippling directly. The Payroll API section below covers that second token — it is optional and only needed if you want payroll data included.

## Who should create the token

Because API tokens inherit the creator's permission profile, the token owner must have access to all the data you want Human Intelligence to sync. We recommend using a **Super Admin** account or a dedicated service account with company-wide read access.

* If the token owner's permissions change after creation, the token's accessible data changes automatically.
* Tokens are **automatically revoked** if the owner is terminated or if the token is unused for more than **30 days**. If this happens, you will need to generate a new token and reconnect.

## Create an API token

* In Rippling, navigate to **Tools > Developer > API Tokens**.
* Click **Create API token**.
* In the **Name** field, enter **"Human Intelligence"**.
* Leave **API version** at the current default.
* On the **Assign scopes** step, enable the scopes listed in the Required scopes section below.
* Complete the creation flow. When the token value is shown, **copy it immediately** — Rippling will not show it again. Treat it as a password.

## Required scopes

Enable the following **read-only** scopes on the token. All scopes listed below are read access only — we do not require any write permissions.

| Scope                          | Data accessed                         | Sensitive |
| ------------------------------ | ------------------------------------- | --------- |
| `workers.read`                 | Employee profiles, employment details | ⚠️ Yes    |
| `users.read`                   | User accounts and identities          | ⚠️ Yes    |
| `compensations.read`           | Compensation records                  | ⚠️ Yes    |
| `departments.read`             | Department structure                  | —         |
| `teams.read`                   | Team membership                       | —         |
| `titles.read`                  | Job titles                            | —         |
| `levels.read`                  | Job levels                            | —         |
| `work-locations.read`          | Work locations                        | —         |
| `employment-types.read`        | Employment type definitions           | —         |
| `companies.read`               | Company entities                      | —         |
| `supergroups.read`             | Supergroup definitions and members    | —         |
| `job-functions.read`           | Job function data                     | —         |
| `custom-fields.read`           | Custom field definitions              | —         |
| `custom-objects.read`          | Custom object types and fields        | —         |
| `custom-object-records.read`   | Custom object record data             | —         |
| `business-partners.read`       | Business partner data                 | ⚠️ Yes    |
| `business-partner-groups.read` | Business partner group data           | —         |

<Info>
  If your organization uses Custom Objects, you will also be prompted to select which object and record types the token can access after enabling the custom object scopes.
</Info>

## Payroll API — a separate token (optional)

Payroll data (payroll runs, per-worker earnings, taxes, and deductions) requires its own token with the **read-only** scopes below. These scopes are not available on a standard customer-created API token, so **contact your Rippling account team or Rippling Support** to request a token with this access. Share the scope list below with them.

| Scope                   | Data accessed                                                                            | Sensitive |
| ----------------------- | ---------------------------------------------------------------------------------------- | --------- |
| `payroll-run`           | Payroll run headers: run type, pay period, pay date, run status                          | —         |
| `worker-payroll-record` | Per-worker per-run detail: gross pay, net pay, earnings, taxes, deductions, garnishments | ⚠️ Yes    |
| `earning-type`          | Earning code dictionary (regular, overtime, bonus, commission, etc.)                     | —         |
| `earnings-input`        | Earnings entered into a run before it is processed                                       | ⚠️ Yes    |

**Read access only.** Rippling exposes write endpoints for some of these resources (e.g. creating or deleting earnings inputs) — we do not need or want write access.

## Connect your API keys in Human Intelligence

* In the Human Intelligence platform, click **Integrations** in the sidebar.
* Locate the **Rippling** HRIS card and click **Connect**.
* Paste the token from the Create an API token section above into the **API Key** field.
* If you obtained a payroll token from the Payroll API section above, paste it into the **Payroll API Key** field. This field is optional — leave it blank if you are not syncing payroll data.
* Click **Connect**.