Skip to main content

​
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

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 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: 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 for details.
1

Log into your Rippling admin dashboard

You need admin access to create API keys.
2

Open Rippling's API access settings

This is where Rippling manages API keys for the v2 REST API.
3

Create a new API key

Create a new API key and give it a recognizable name, for example “Serval Integration”.
4

Select your scopes

Choose the scopes from the table above that match how you plan to use the integration.
5

Copy and securely store the key

The generated API key is only shown once - copy it before closing the page.
The key must be for Rippling’s v2 REST API. Keys for Rippling’s legacy platform API will not work with this integration.

​
Connect in Serval

1

Open the Rippling connect form

In Serval, add the Rippling integration to open its connect form.
2

Enter your Company Name

A free-text field that becomes the display name of this connection in Serval.
3

Paste your API Key (v2)

A password-type field for the Rippling API key you created above.
4

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.”
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.
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.

​
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.
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.

​
Gotchas and troubleshooting

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.
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.
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.
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.
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.
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.
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.
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.
Need help? Contact support@serval.com for assistance with your Rippling integration.