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

# Rippling

> Connect Rippling to Serval to sync your workforce and supergroups, manage supergroup membership, and call the Rippling API from custom workflows.

## About Rippling

Rippling is a workforce management platform that combines HR, IT, payroll, and finance in one place. Serval connects to Rippling with an API key and automatically imports your Rippling workers as Serval users and your supergroups as group resources. Serval can also grant and revoke supergroup membership through access management, and your custom workflows can reach the full Rippling API through a typed request action.

**Authentication:** Rippling API key (v2), stored encrypted and sent by Serval as a bearer token on every request it makes to Rippling on your behalf.

**Data sync:** Two background full syncs run every 4 hours - one for users (workers) and one for groups (supergroups). Membership changes you make through Serval's access management are applied on demand.

## What the Rippling integration enables

| Capability                     | Description                                                                                                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| User sync (HRIS)               | Imports Rippling workers as Serval users every 4 hours, capturing work email, preferred or given names, and active status.                                                                                               |
| Group sync (supergroups)       | Imports Rippling supergroups of type ALIAS as Serval group resources every 4 hours, each with a single "member" entitlement and the members on its inclusion list. Supergroups also feed Serval's org-group information. |
| Access management provisioning | Grants and revokes supergroup membership for Serval users, matched to Rippling workers by exact work email.                                                                                                              |
| Health checks                  | Four built-in checks verify that Serval can authenticate and has the read access the syncs depend on.                                                                                                                    |
| Custom workflow API access     | A typed Rippling API request action exposes more than 30 Rippling REST endpoints - companies, departments, teams, workers, users, supergroups, custom objects and their records, and more - to your custom workflows.    |

The integration ships no pre-packaged workflow templates: user sync, group sync, and provisioning are built-in platform capabilities, and everything else is available through custom workflows. Anything defined in the [Rippling API](https://developer.rippling.com/) can be accessed through Serval.

## Get your credentials

Serval needs a Rippling API key for the **v2 REST API** with **API Tier 1** access. The scopes you grant determine what Serval can do:

| Scope                  | Needed for                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| sso-me.read            | The connection health check                                                                   |
| workers.read           | User sync and worker lookup during provisioning                                               |
| users.read             | The "List Rippling Users" health check                                                        |
| supergroups.read       | Group sync and membership sync                                                                |
| supergroups.read-write | Access management provisioning - only if you want Serval to add and remove supergroup members |

Additional read scopes (companies.read, departments.read, teams.read, custom-fields.read, and so on) are only needed if your custom workflows call those parts of the API. See the [Rippling developer documentation](https://developer.rippling.com/) for details.

<Steps>
  <Step title="Log into your Rippling admin dashboard">
    You need admin access to create API keys.
  </Step>

  <Step title="Open Rippling's API access settings">
    This is where Rippling manages API keys for the v2 REST API.
  </Step>

  <Step title="Create a new API key">
    Create a new API key and give it a recognizable name, for example "Serval Integration".
  </Step>

  <Step title="Select your scopes">
    Choose the scopes from the table above that match how you plan to use the integration.
  </Step>

  <Step title="Copy and securely store the key">
    The generated API key is only shown once - copy it before closing the page.
  </Step>
</Steps>

<Warning>
  The key must be for Rippling's v2 REST API. Keys for Rippling's legacy platform API will not work with this integration.
</Warning>

## Connect in Serval

<Steps>
  <Step title="Open the Rippling connect form">
    In Serval, add the **Rippling** integration to open its connect form.
  </Step>

  <Step title="Enter your Company Name">
    A free-text field that becomes the display name of this connection in Serval.
  </Step>

  <Step title="Paste your API Key (v2)">
    A password-type field for the Rippling API key you created above.
  </Step>

  <Step title="Save">
    If installation fails, you will see "Failed to install integration" with details from the backend appended, or the general message "Failed to save configuration. Please try again."
  </Step>
</Steps>

<Warning>
  Neither field is marked required and there is no validation on the form - it will submit with blanks. A blank submission creates a connection that simply fails every health check, so always fill in both fields.
</Warning>

<Note>
  **Editing the connection later:** when you reopen the configuration, the API key appears masked (bullets plus the last 4 characters). Leaving it untouched keeps your stored key, and so does choosing to replace it but leaving the field blank - to rotate, paste the complete new key. Leaving Company Name blank keeps the existing name; entering a new value renames the connection. If an update fails, the integration settings page shows "Failed to update configuration", while the configure dialog shows "Failed to update integration:" followed by error details.
</Note>

## Verifying the connection

After connecting, four health checks confirm the integration is working:

* **Test Rippling Connection** - verifies Serval can authenticate and reach Rippling, reporting the connected account. Success: "Successfully connected to Rippling as \[email]." Failure: "Unable to reach Rippling." followed by a shared error explanation (see the troubleshooting section below).
* **List Rippling Workers** - verifies the read access to employee data that user sync depends on. Success: "Successfully retrieved workers list from Rippling (found \[number] worker(s) in sample)." Failure: "Unable to list workers from Rippling." plus the shared suffix.
* **List Rippling Supergroups** - verifies the read access to ALIAS supergroups that group sync depends on. Success: "Successfully retrieved supergroups list from Rippling (found \[number] supergroup(s) in sample)." Failure: "Unable to list supergroups from Rippling." plus the shared suffix.
* **List Rippling Users** - verifies read access to user account data. Success: "Successfully retrieved users list from Rippling (found \[number] user(s) in sample)." Failure: "Unable to list users from Rippling." plus the shared suffix.

<Tip>
  If "Test Rippling Connection" is green but the worker, supergroup, or user checks fail, your key authenticates but is missing read scopes - the connection check only needs the identity scope. Note also that all four checks can pass while provisioning still fails, because none of them test the write scope (supergroups.read-write) that adding and removing supergroup members requires.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="A 401 error mentions an 'OAuth token', but this integration uses an API key">
    All four health checks share the same error wording. On a 401 you will see "The OAuth token may have expired or been revoked. Please reconnect your Rippling integration." - in practice this means your API key is invalid or has been revoked; re-open the configuration and paste a new key. Other shared messages: 403 - "This may be due to missing API scopes. Please check that your Rippling application has the required permissions (API Tier 1)."; 404 - "The requested resource was not found. This may indicate a configuration issue."; 429 - "Rippling rate limit reached. Please try again in a few moments."; 500 - "Rippling API is experiencing issues. Please try again later."; anything else - "Error:" followed by the underlying details.
  </Accordion>

  <Accordion title="Only ALIAS-type supergroups are synced">
    Group sync and the supergroups health check only look at supergroups whose group type is ALIAS. Supergroups of any other type in Rippling will not appear as Serval resources.
  </Accordion>

  <Accordion title="Provisioning matches users by exact work email">
    When granting or revoking supergroup membership, Serval finds the Rippling worker by exact work email match. It fails with "No worker found with email: \[email]" when there is no match, and "Multiple workers found with email: \[email]" when the email is ambiguous. Serval user emails must match Rippling work emails exactly.
  </Accordion>

  <Accordion title="Membership is read from, and written to, inclusion members only">
    Both the synced member list and Serval's grant and revoke operations work against the supergroup's inclusion-members list. If a user is blocked by the supergroup's exclusion-members list, adding them through Serval will not give them effective membership - Serval never modifies exclusion lists. Inclusion members without a work email in Rippling are skipped during membership sync and will not appear in the synced member list.
  </Accordion>

  <Accordion title="Your API key must be for the v2 REST API">
    All Serval traffic goes to rest.ripplingapis.com using bearer authentication with API Tier 1 access. Keys issued for Rippling's legacy platform API will not work - create the key under Rippling's v2 REST API access.
  </Accordion>

  <Accordion title="The connect form does not require any fields">
    Neither Company Name nor API Key (v2) is marked required, and there is no validation in the form or backend. Submitting blanks installs a connection that fails every health check - fill in both fields when connecting.
  </Accordion>

  <Accordion title="Rotating or keeping your API key when editing the connection">
    The masked key (bullets plus last 4 characters) shown on the edit form is a placeholder. Leaving it as-is keeps the stored key, and so does replacing it with a blank value; pasting a complete new key replaces it. Similarly, a blank Company Name keeps the existing connection name.
  </Accordion>

  <Accordion title="How deactivated workers are detected">
    A worker is marked deactivated only when their linked Rippling user account is inactive. Workers without a linked user account are treated as active, and workers without a work email sync into Serval with an empty email.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your Rippling integration.