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

# Setup

> Connect Rippling to Ravenna using an API token with workers, users, teams, and departments read scopes to enable automatic employee data sync.

<Info>Connect to Rippling using an API token for employee data synchronization</Info>

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

<Steps>
  <Step title="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
  </Step>

  <Step title="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
  </Step>
</Steps>

<Warning>
  Store your API token securely. You will not be able to view the full token again after creation.
</Warning>

## Setup guide

<Steps>
  <Step title="Navigate to integrations">
    1. Go to **Settings > Integrations**
    2. Find **Rippling** in the HRIS section
  </Step>

  <Step title="Select Rippling">
    Click **Connect** on the Rippling integration card.
  </Step>

  <Step title="Enter your API token">
    Paste the API token you generated in Rippling.

    <ParamField path="apiToken" type="string" required>
      Your Rippling API token with the required read scopes
    </ParamField>
  </Step>

  <Step title="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)
  </Step>

  <Step title="Complete setup">
    Click **Connect** to complete the integration. The initial data sync begins automatically.

    <Info>
      Data syncs automatically every 24 hours after the initial sync. You can view the last sync time in the integration settings.
    </Info>
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Invalid API token error">
    **Cause**: The API token is incorrect, expired, or missing required scopes

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Employees not syncing">
    **Cause**: Sync not yet complete, filter settings, or missing API scopes

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Teams or departments missing">
    **Cause**: Missing API scopes or group type filter settings

    **Solution**:

    * 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
  </Accordion>

  <Accordion title="Insufficient permissions error">
    **Cause**: API token missing required scopes

    **Solution**:

    * 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`
  </Accordion>
</AccordionGroup>