> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/hris/rippling.md).

# Rippling

Harmony supports Rippling as an HRIS integration, allowing you to connect your Rippling account directly from the integrations settings. Once connected, your Rippling API token is stored encrypted, keeping your credentials secure.

### Prerequisites

Before connecting Rippling, make sure you have the following:

* An active Rippling account with API access enabled
* A Rippling user who can create API tokens (**Create and manage API tokens**) and whose permission profile covers the entire company. A token can only read the employees and fields its creator can see, so a token created by someone scoped to their own reports syncs only part of your company
* A Rippling API token with the permissions listed in [Required API Token Permissions](#required-api-token-permissions)
* Admin access to your Harmony workspace

### Required API Token Permissions

When you create the API token in Rippling, grant it read access to the following data objects. Harmony reads employee data only - it never writes back to Rippling.

| Scope                   | Data object      | Why Harmony needs it                                                                                                                                          |
| ----------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workers.read`          | Workers          | The core employee record: employment status, job title, start and end dates, work email, and the manager relationship used to build your reporting hierarchy. |
| `users.read`            | Users            | Employee first and last name, display name, time zone, and profile photo.                                                                                     |
| `departments.read`      | Departments      | The department each employee belongs to.                                                                                                                      |
| `employment-types.read` | Employment types | Full-time, part-time, and temporary classification, plus whether the person is an employee or a contractor.                                                   |

These four scopes are all Harmony reads - no other Rippling data is accessed. Without `workers.read`, Rippling rejects the token and Harmony cannot connect. Without one of the other three, Rippling returns those details empty, so names, departments, or employment types are missing in Harmony.

{% hint style="info" %}
If you adjust the token's permissions later, the change takes effect on the next sync - you do not need to reconnect the integration.
{% endhint %}

### Create the API Token in Rippling

1. In Rippling, go to **Developer** > **API credentials** and click **New API token**.
2. Enter a name for the token, for example `Harmony`.
3. Select the four scopes listed above.
4. Click **Create** and copy the token. Rippling shows it only once.

The token acts as the user who created it. Rippling revokes it if that user is terminated or if the token goes unused for more than 30 days.

### Connect Your Rippling Account

To link your Rippling account to Harmony:

1. In Harmony, navigate to **Settings** and open the **Integrations** section.
2. Find **Rippling (HRIS)** under **HRIS** (or search for it by name) and click its card.
3. Enter your Rippling API token in the **API Key** field.
4. Click **Connect** to confirm the connection.

Harmony checks the token with Rippling before saving it. If Rippling rejects it, verify the token and that it has permission to read workers. Once saved, your API token is encrypted and stored securely.

### What to Expect Next

Once connected, Harmony syncs employee data from Rippling automatically on an ongoing basis, including name, work email, job title, department, manager, employment status and type, start and end dates, time zone, and profile photo.

### Disconnect Rippling

If you need to remove the Rippling integration at any time:

1. Go to **Settings** and open the **Integrations** section.
2. Click the **Rippling (HRIS)** card and click **Disconnect**.
3. Confirm the action when prompted.

Disconnecting will remove your stored API token from Harmony.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.harmony.io/integrations/hris/rippling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.