A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Rippling API is how an app or AI agent works with a company's HR data: reading the worker directory, looking up departments, teams, and work locations, and listing or filing time-off requests. Access is granted through an OAuth grant or an API key, and a set of scopes decides which resources a call can read or write, with each token reaching exactly one Rippling company. Rippling can also push employee lifecycle events, like a hire or a termination, to a registered webhook URL.
How an app or AI agent connects to Rippling determines what it can reach. Access runs through an OAuth grant or an API key, and one token reaches exactly one Rippling company, so an integration installed across many companies holds one token per company.
The newer REST API answers at https://rest.ripplingapis.com and covers organizational data, like workers, departments, teams, work locations, and time off. A call authenticates with a Bearer token, and lists support filter, expand, and order_by parameters with cursor pagination.
The older Platform API answers at https://api.rippling.com/platform/api and still serves a few methods the REST API has not yet replaced, including creating and updating a leave request and managing groups for app provisioning. It uses the same Bearer-token authentication.
Rippling posts an event to a registered URL when an employee lifecycle event happens, like a hire, a termination, or a profile update. Webhooks are configured per app in the developer portal so the integration learns about activity without polling.
An app registered in the developer portal sends a user through the OAuth authorization-code flow, then exchanges the returned code for access and refresh tokens. Each access token reaches one Rippling company, and the fields a call can read depend on the scopes the customer authorized.
An API key authenticates server-to-server calls for a single organization, sent as a Bearer token in the Authorization header. It suits an integration that works with one company and does not need a per-user OAuth flow.
The Rippling API is split into areas an agent can act on, like the worker directory, departments, teams, work locations, and time off. Each area carries its own permission, and writes are concentrated in a few areas, such as leave requests and groups.
List and read the people in a company, including active and terminated workers, and read a single worker by id.
List and read departments, teams, work locations, and levels that describe how a company is organized.
List leave requests, leave balances, and leave types, and create or process a leave request.
List and read job functions and employment types that classify a worker's role and employment.
Read the current company and list the legal entities under it.
List and read user accounts, read the authenticated context, and list the entitlements granted.
Create, read, update, and delete groups, used to drive third-party app membership.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Workers (employees)List and read the people in a company, including active and terminated workers, and read a single worker by id.5 | ||||||
| GET | /workers | List the workers in a company, with filter, expand, and order_by query parameters. | read | workers:read | Current | |
On the REST API surface (rest.ripplingapis.com). The fields returned depend on the scopes the customer authorized. Acts onworker Permission (capability) workers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /workers/{id} | Retrieve a single worker by id. | read | workers:read | Current | |
On the REST API surface. Read-only. Acts onworker Permission (capability) workers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /employees | List the active employees provisioned in a company, on the older Platform API. | read | employee:read | Current | |
On the older Platform API surface (api.rippling.com/platform/api). The REST API list-workers method is the newer equivalent. Acts onemployee Permission (capability) employee:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /employees/include_terminated | List both active and terminated employees, on the older Platform API. | read | employee:read | Current | |
On the older Platform API surface. Returns terminated workers that the active list omits. Acts onemployee Permission (capability) employee:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /employees/{employeeId} | Retrieve a single employee by id, on the older Platform API. | read | employee:read | Current | |
On the older Platform API surface. Read-only. Acts onemployee Permission (capability) employee:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Org structureList and read departments, teams, work locations, and levels that describe how a company is organized.5 | ||||||
| GET | /departments | List a company's departments, including the parent department where one applies. | read | departments:read | Current | |
On the REST API surface. Read-only. Acts ondepartment Permission (capability) departments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /departments/{id} | Retrieve a single department by id. | read | departments:read | Current | |
On the REST API surface. Read-only. Acts ondepartment Permission (capability) departments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /teams | List a company's teams, including the parent team for any subteam. | read | teams:read | Current | |
On the REST API surface. Each team carries id, name, and parent. Acts onteam Permission (capability) teams:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /work-locations | List a company's work locations, each with a nickname and address details. | read | work_locations:read | Current | |
On the REST API surface. Read-only. Acts onwork location Permission (capability) work_locations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /levels | List a company's levels, the set positions in an organization such as Manager or Executive. | read | levels:read | Current | |
On the REST API surface. Read-only. Acts onlevel Permission (capability) levels:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Time off (leave)List leave requests, leave balances, and leave types, and create or process a leave request.4 | ||||||
| GET | /leave-requests | List leave requests, filtered by date or status. | read | leave:read | Current | |
On the REST API surface. Read-only; requires the leave read scope. Acts onleave request Permission (capability) leave:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /leave-balances | List the leave balances for the workers in a company. | read | leave:read | Current | |
On the REST API surface. Read-only. Acts onleave balance Permission (capability) leave:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /leave_requests | Create a leave request for a worker, on the older Platform API. | write | leave:write | Current | |
On the older Platform API surface (api.rippling.com/platform/api). Rippling marks this method alpha, so it can change. Acts onleave request Permission (capability) leave:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PATCH | /leave_requests/{leaveRequestId} | Update an existing leave request, on the older Platform API. | write | leave:write | Current | |
On the older Platform API surface. Changes the dates or details of a pending request. Acts onleave request Permission (capability) leave:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Job structureList and read job functions and employment types that classify a worker's role and employment.3 | ||||||
| GET | /job-functions | List the job functions that classify the roles in a company. | read | job_functions:read | Current | |
On the REST API surface. Read-only. Acts onjob function Permission (capability) job_functions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /employment-types | List the employment types that classify how a worker is employed. | read | employment_types:read | Current | |
On the REST API surface. Read-only. Acts onemployment type Permission (capability) employment_types:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /employment-types/{id} | Retrieve a single employment type by id. | read | employment_types:read | Current | |
On the REST API surface. Read-only. Acts onemployment type Permission (capability) employment_types:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Companies & legal entitiesRead the current company and list the legal entities under it.2 | ||||||
| GET | /companies/current | Get the company the current token is scoped to, on the older Platform API. | read | company:read | Current | |
On the older Platform API surface. One token reaches one company, and this returns that company. Acts oncompany Permission (capability) company:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /companies | List the companies reachable from the current context. | read | companies:read | Current | |
On the REST API surface. Read-only. Acts oncompany Permission (capability) companies:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & accessList and read user accounts, read the authenticated context, and list the entitlements granted.4 | ||||||
| GET | /users | List the user accounts in a company. | read | users:read | Current | |
On the REST API surface. Read-only. Acts onuser Permission (capability) users:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /me | Retrieve the authenticated context for the current token, used to validate access, on the older Platform API. | read | — | Current | |
On the older Platform API surface. Confirms which company and account a token resolves to. Acts onuser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /entitlements | List the entitlements granted in a company, the access rights tied to accounts. | read | entitlements:read | Current | |
On the REST API surface. Read-only. Acts onentitlement Permission (capability) entitlements:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /saml/idp_metadata | Get the SAML identity-provider metadata, used to set up single sign-on with Rippling as the identity provider. | read | sso:read | Current | |
On the older Platform API surface. Rippling acts as the SAML identity provider that pushes provisioning out to other apps, rather than accepting inbound provisioning. Acts onsso metadata Permission (capability) sso:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
GroupsCreate, read, update, and delete groups, used to drive third-party app membership.3 | ||||||
| POST | /groups | Create a group, used to drive membership in a third-party app, on the older Platform API. | write | group:write | Current | |
On the older Platform API surface. A group maps Rippling membership onto an app the integration provisions. Acts ongroup Permission (capability) group:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /groups/{groupId} | Update a group's details and membership, on the older Platform API. | write | group:write | Current | |
On the older Platform API surface. Changing membership can change who has access to the provisioned app. Acts ongroup Permission (capability) group:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /groups/{groupId} | Delete a group, on the older Platform API. | write | group:write | Current | |
On the older Platform API surface. Removing a group removes the membership it represented. Acts ongroup Permission (capability) group:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Rippling can notify an app or AI agent when something happens in a company, like an employee being hired, updated, or terminated, instead of the app repeatedly asking. Webhooks are registered per app in the Rippling developer portal and delivered to a chosen endpoint URL.
| Event | What it signals | Triggered by |
|---|---|---|
employee.created | Fires when a new employee is created in a company, such as a new hire being onboarded. | In-app only |
employee.updated | Fires when an employee record changes, such as a profile, department, or manager update. | In-app only |
employee.terminated | Fires when an employee is terminated, the signal to deprovision the access an integration granted. | In-app only |
Rippling limits how fast an app or AI agent can call, and returns a 429 response when a caller goes too fast. The exact per-minute numbers are not published, so an integration should back off on a 429 and retry rather than assume a fixed ceiling.
Rippling rate-limits API calls and returns HTTP 429 with the message 'Rate limit exceeded. Please try again later.' when a caller goes too fast. Rippling does not publish the exact per-minute or per-tier numbers in its public documentation, so an integration should not assume a fixed ceiling. The reliable approach is to handle 429 defensively, backing off and retrying with exponential backoff rather than hammering the endpoint, and to contact Rippling developer support for partner-tier limits where a higher allowance is needed.
The REST API uses cursor pagination. A list response returns a results array and a next_link holding the URL for the next page, and the cursor parameter advances through pages. The limit parameter sets the page size, defaulting to 50 with a maximum of 100. The older Platform API uses limit and offset parameters instead, with a recommended maximum limit of 100, and the company-activity endpoint advances with a next cursor.
Responses are JSON. A list page returns at most 100 records, the maximum value of limit. The expand parameter can pull in related records inline, supporting up to two levels of expansion and up to ten expanded fields per request, which trades a larger response for fewer round trips.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 401 | Unauthorized | Authentication is missing or invalid, for example a missing or expired API key or OAuth token. The body returns an error and a message, such as 'Missing or invalid API key'. | Send a valid Bearer token in the Authorization header, and refresh an expired OAuth token. |
| 403 | Forbidden | The token is valid but lacks the scope the request needs, so the call is not permitted. | Grant the missing scope on the app, then have the customer reauthorize. |
| 404 | Not Found | The requested resource does not exist, or is not visible to the company the token is scoped to. The body returns an error and a message, such as 'The requested resource does not exist'. | Confirm the id and that the resource belongs to the same company as the token. |
| 422 | Validation Error | The request was well-formed but a field failed validation. The body returns a details object naming the field and the problem, such as an invalid email format. | Read the details object, correct the named field, and resend. |
| 429 | Too Many Requests | The caller exceeded the rate limit. The body returns the message 'Rate limit exceeded. Please try again later.' | Back off and retry after a short wait, ideally with exponential backoff, since the exact ceiling is not published. |
Rippling runs two API surfaces side by side. The newer REST API, branded the Rippling Platform API, is the current surface for organizational data, and the older Platform API still serves a few write actions, like creating a leave request.
The REST API, branded the Rippling Platform API, is the current surface for organizational data, answering at rest.ripplingapis.com. It uses plural collection paths like /workers and /departments, cursor pagination with a results array and a next_link, and filter, expand, and order_by query parameters. Rippling generates the OpenAPI spec from typed definitions, so the published documentation tracks the live schema. New integrations should target this surface.
The older Platform API answers at api.rippling.com/platform/api and predates the REST API. It exposes employees under /employees with limit and offset pagination, and still serves a few methods the REST API has not yet replaced, including creating and updating a leave request, which Rippling marks alpha, and managing groups used to provision third-party apps. It remains supported alongside the REST API.
New work should target the REST API surface, and fall back to the older Platform API only where a method has not yet moved across.
Rippling REST API docs ↗Bollard AI sits between a team's AI agents and Rippling. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.