Skip to main content
Connect to Rippling using an API token for employee data synchronization
This guide walks you through connecting your Rippling instance to Ravenna for employee and group synchronization.

​
Prerequisites

Before you begin, ensure you have:
  • An active Rippling account with admin access
  • A Rippling API token with the required scopes

​
Generate an API token

Create an API token in Rippling with the following scopes:
  • workers.read - Read employee/worker data
  • users.read - Read user account data
  • teams.read - Read team information
  • departments.read - Read department information
1

Navigate to Rippling API settings

  1. Log in to your Rippling admin account
  2. Go to your company settings or API configuration section
  3. Navigate to the API tokens management area
2

Create a new API token

  1. Click Create API Token or equivalent
  2. Provide a descriptive name (e.g., “Ravenna Integration”)
  3. Select the required scopes: workers.read, users.read, teams.read, departments.read
  4. Generate the token and copy it securely
Store your API token securely. You will not be able to view the full token again after creation.

​
Setup guide

1

Navigate to integrations

  1. Go to Settings > Integrations
  2. Find Rippling in the HRIS section
2

Select Rippling

Click Connect on the Rippling integration card.
3

Enter your API token

Paste the API token you generated in Rippling.
​
apiToken
string
required
Your Rippling API token with the required read scopes
4

Configure sync settings

After connecting, configure your sync preferences:
  • Employee status filter: Choose which employment statuses to sync (default: Active only). Options include Active, Inactive, Terminated, and Pending.
  • Group type filter: Select which group types to sync (default: Teams and Departments)
5

Complete setup

Click Connect to complete the integration. The initial data sync begins automatically.
Data syncs automatically every 24 hours after the initial sync. You can view the last sync time in the integration settings.

​
Troubleshooting

Cause: The API token is incorrect, expired, or missing required scopesSolution:
  • Verify the token was copied correctly without extra spaces
  • Check that the token has all four required scopes: workers.read, users.read, teams.read, departments.read
  • Generate a new token if the current one is invalid
  • Ensure the token has not been revoked in Rippling
Cause: Sync not yet complete, filter settings, or missing API scopesSolution:
  • Check the last sync time in integration settings
  • Verify your employee status filter includes the statuses you expect
  • Ensure the API token has the workers.read and users.read scopes
  • Wait for the next 24-hour sync cycle
Cause: Missing API scopes or group type filter settingsSolution:
  • Ensure the API token has teams.read and departments.read scopes
  • Check that your group type filter includes both Teams and Departments
  • Verify that the groups exist in Rippling
  • Wait for the next sync cycle to pick up new groups
Cause: API token missing required scopesSolution:
  • Generate a new API token with all required scopes
  • Update the token in the Ravenna integration settings
  • Required scopes: workers.read, users.read, teams.read, departments.read