Rippling User Management API Guide

Auth method: OAuth 2.0 (authorization code flow); API key also available for server-to-server integrations via the developer portal

Setup steps

1. Register an application in the Rippling Developer Portal (developer.rippling.com) to obtain a client_id and client_secret.
2. Direct the Rippling account admin to the OAuth authorization URL: https://app.rippling.com/apps/PLATFORM//authorize with required scopes.
3. Exchange the returned authorization code for an access_token and refresh_token via POST https://api.rippling.com/auth/oauth2/token.
4. Include the access token in all API requests as a Bearer token in the Authorization header.
5. Refresh the access token using the refresh_token before expiry; Rippling tokens expire and must be refreshed.

Required scopes

List employees

• Method: GET
• URL: https://api.rippling.com/platform/api/employees
• Watch out for: Returns only employees visible to the OAuth app's authorized company. Terminated employees may be excluded by default; check filter params.

Request example

GET /platform/api/employees?limit=25
Authorization: Bearer <access_token>

Response example

{
  "data": [
    {"id": "emp_abc123", "workEmail": "jane@acme.com",
     "firstName": "Jane", "lastName": "Doe",
     "employmentStatus": "ACTIVE"}
  ],
  "nextCursor": "cursor_xyz"
}

Get employee by ID

• Method: GET
• URL: https://api.rippling.com/platform/api/employees/{id}
• Watch out for: The {id} must be Rippling's internal employee ID, not an email or external HR ID.

Request example

GET /platform/api/employees/emp_abc123
Authorization: Bearer <access_token>

Response example

{
  "id": "emp_abc123",
  "workEmail": "jane@acme.com",
  "firstName": "Jane",
  "lastName": "Doe",
  "title": "Engineer",
  "employmentStatus": "ACTIVE"
}

Create employee

• Method: POST
• URL: https://api.rippling.com/platform/api/employees
• Watch out for: Creating an employee via API may trigger onboarding workflows and app provisioning configured in Rippling. Ensure downstream app licenses are available.

Request example

POST /platform/api/employees
Authorization: Bearer <access_token>
Content-Type: application/json

{"firstName":"John","lastName":"Smith",
 "workEmail":"john@acme.com",
 "startDate":"2025-06-01",
 "employmentType":"EMPLOYEE"}

Response example

{
  "id": "emp_new456",
  "workEmail": "john@acme.com",
  "employmentStatus": "ACTIVE"
}

Update employee

• Method: PATCH
• URL: https://api.rippling.com/platform/api/employees/{id}
• Watch out for: Partial updates are supported. Changing department or manager may trigger automated role-change workflows in Rippling.

Request example

PATCH /platform/api/employees/emp_abc123
Authorization: Bearer <access_token>
Content-Type: application/json

{"title": "Senior Engineer",
 "department": {"id": "dept_789"}}

Response example

{
  "id": "emp_abc123",
  "title": "Senior Engineer",
  "department": {"id": "dept_789", "name": "Engineering"}
}

List departments

• Method: GET
• URL: https://api.rippling.com/platform/api/departments
• Watch out for: Department IDs are required when assigning employees to departments via the employees endpoint.

Request example

GET /platform/api/departments
Authorization: Bearer <access_token>

Response example

{
  "data": [
    {"id": "dept_789", "name": "Engineering"},
    {"id": "dept_101", "name": "Sales"}
  ]
}

List groups

• Method: GET
• URL: https://api.rippling.com/platform/api/groups
• Watch out for: Groups in Rippling map to teams/security groups used for app access policies. Requires group:read scope.

Request example

GET /platform/api/groups
Authorization: Bearer <access_token>

Response example

{
  "data": [
    {"id": "grp_001", "name": "Engineering Team",
     "members": ["emp_abc123"]}
  ]
}

Get current authenticated company

• Method: GET
• URL: https://api.rippling.com/platform/api/me
• Watch out for: Useful for validating the OAuth token's company context before making employee queries.

Request example

GET /platform/api/me
Authorization: Bearer <access_token>

Response example

{
  "companyId": "co_xyz",
  "companyName": "Acme Corp"
}

List leaves (time-off)

• Method: GET
• URL: https://api.rippling.com/platform/api/leaves
• Watch out for: Requires leave:read scope. Leave data availability depends on whether the company has Rippling's Time & Attendance module enabled.

Request example

GET /platform/api/leaves?employeeId=emp_abc123
Authorization: Bearer <access_token>

Response example

{
  "data": [
    {"id": "leave_001", "employeeId": "emp_abc123",
     "startDate": "2025-07-01", "endDate": "2025-07-05",
     "type": "PTO"}
  ]
}

• Rate limits: Rippling's public developer documentation does not explicitly publish specific rate limit numbers or tier-based quotas as of the last known documentation review.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No explicit rate limit values, headers, or Retry-After behavior documented publicly. Contact Rippling developer support for partner-tier limits.

• Pagination method: cursor

• Default page size: 25

• Max page size: 100

• Pagination pointer: cursor / limit

• Webhooks available: Yes

• Webhook notes: Rippling supports webhooks for app integrations built on the Rippling platform. Webhook events are delivered to a registered endpoint URL when employee lifecycle events occur (e.g., hire, termination, profile update). Webhooks are configured per-app in the Rippling Developer Portal.

• Alternative event strategy: Polling the GET /employees endpoint with a lastModified filter can serve as a fallback if webhooks are not available for a given integration tier.

• Webhook events: employee.created, employee.updated, employee.terminated, employee.rehired, employee.department_changed, employee.manager_changed

• SCIM available: No
• SCIM version: Not documented
• Plan required: Custom
• Endpoint: Not documented

Limitations:

• Rippling functions as a SCIM identity provider that pushes provisioning TO other apps (e.g., via its App Shop connectors), not as a SCIM-inbound target for external IdPs.
• There is no publicly documented inbound SCIM 2.0 endpoint for provisioning users INTO Rippling from an external IdP.
• User management into Rippling is handled via its native REST API or direct HR workflows, not via SCIM.

Three integration patterns cover the majority of production use cases.

Onboarding: POST to /platform/api/employees with firstName, lastName, workEmail, startDate, and employmentType.

Store the returned id.

App provisioning automations in Rippling fire asynchronously - an ACTIVE employmentStatus on the employee record does not guarantee all connected apps are provisioned immediately.

Verify via the App Management UI or a follow-up GET.

Profile sync: Register a webhook for employee.updated events in the Developer Portal.

On receipt, extract the id from the payload and re-fetch the full record via GET /platform/api/employees/{id} - webhook payloads may contain only changed fields, not the complete object.

Map Rippling fields to your target schema before writing.

Offboarding: Consume the employee.terminated webhook or poll for employmentStatus=INACTIVE.

Confirm endDate via GET /platform/api/employees/{id}, then trigger deprovisioning in external systems using workEmail or id.

Rippling's App Shop deprovisioning fires automatically for its own connected apps - it does not cover systems outside that ecosystem.

Onboard a new hire and verify provisioning

1. POST /platform/api/employees with required fields (firstName, lastName, workEmail, startDate, employmentType).
2. Store the returned employee id for future reference.
3. Poll GET /platform/api/employees/{id} or listen for the employee.created webhook to confirm the record is ACTIVE.
4. Verify downstream app provisioning was triggered by checking Rippling's App Management UI or querying connected app status if available via API.

Watch out for: App provisioning automations in Rippling are triggered asynchronously; the employee record being ACTIVE does not guarantee all connected apps are provisioned immediately.

Sync employee profile changes to an external system

1. Register a webhook endpoint in the Rippling Developer Portal to receive employee.updated events.
2. On webhook receipt, extract the employee id from the payload.
3. Call GET /platform/api/employees/{id} to fetch the full updated employee record.
4. Map Rippling fields to the external system's schema and apply the update.

Watch out for: Webhook payloads may contain only the changed fields or a reference ID, not the full employee object. Always re-fetch the full record via the REST API to ensure data completeness.

Offboard a terminated employee

1. Receive the employee.terminated webhook event or detect termination by polling for employees with employmentStatus=INACTIVE.
2. Call GET /platform/api/employees/{id} to confirm endDate and employmentStatus.
3. Trigger deprovisioning logic in external systems using the employee's workEmail or id.
4. Rippling's own connected app deprovisioning (App Shop integrations) fires automatically based on termination; no additional API call is needed for Rippling-managed apps.

Watch out for: Rippling's automated deprovisioning for its App Shop integrations is separate from any external system deprovisioning you implement. Do not assume Rippling's offboarding covers systems not connected via the App Shop.

Several non-obvious constraints create integration risk. Employee creation via API triggers Rippling's configured onboarding automations - app provisioning, equipment requests, and compliance tasks fire immediately in production environments; test against a sandbox tenant before going live.

Pagination is cursor-based only (cursor / limit params, default page size 25, max 100); offset-based pagination is not supported - always advance using the nextCursor value from the response. Custom fields (customFields) are company-specific;

field keys must be retrieved from the target company's Rippling configuration before use and cannot be assumed stable across tenants. Rate limit values are not publicly documented - implement exponential backoff and handle HTTP 429 responses defensively.

Changing department or manager via PATCH may trigger automated role-change workflows in Rippling, with downstream effects on app access policies. Finally, the /platform/api base path is specific to the partner/developer API; do not conflate it with internal Rippling service URLs.