Skip to content
docs/Guides/Connect Rippling

Connect Rippling

Create a Rippling API token, connect it, and give sessions your org chart and HR records.

≈ 3 minmarkdownedit on github ↗

Connecting Rippling lets sessions read your HR system through the Rippling REST API: workers and their managers, users, departments, teams, locations, titles and levels, employment types, legal entities, leave, time, devices, worker changes, the activity log, custom objects, and reports, plus the writes Rippling exposes on those records.

Rippling’s REST API is part of the Rippling API subscription, and the token is created by an admin in the API Tokens app. If the app shows “Permission denied”, your company has no API subscription, the app is not installed, or your admin role lacks the permission to manage tokens; a Rippling account owner resolves that in Rippling.

  1. In Rippling, open the API Tokens app (app.rippling.com/api-tokens, or search for it from the dashboard) and create a new token. Give it a name, pick the API version, and choose the scopes the sessions need; each read command below names the scope family it uses, such as workers.read or departments.read.
  2. Copy the token; Rippling shows it once. Rippling revokes a token that is unused for 30 days or whose owner leaves, so create it under a service admin where you can.

Open Settings → Integrations → Rippling → Connect and paste the token. engrams seals it as the org secret rippling.api_token and tests it with one read of the company record.

The token never enters a sandbox. The egress proxy adds it to each request as a bearer token and removes any token the agent supplies. Fields the token is not entitled to read come back redacted, listed under __meta.redacted_fields in each response.

A profile grants Rippling powers by area, each split into read and write: workers:read, org:read and org:write (departments, teams, locations, titles, levels, job catalog), hiring, compensation, payroll, leave, time, devices, custom-objects, reports, files, workflows, activity-log:read, and company:read. Workers, users, and the activity log are read-only because the API offers no writes there.

The rippling command is on the PATH in every session whose profile grants at least one Rippling power. It is a generic client over the whole API: every resource is reached through list, get, create, update, and delete, resources prints the resource table with the verbs each supports, and api reaches any other route. Query fields pass straight through in Rippling’s own filter, expand, and order_by syntax, and list follows every page and prints one JSON array. Run rippling with no arguments for the command list, or engrams-integrations for every connected tool.

Terminal windowbash
rippling list workers "filter=work_email eq 'someone@example.com'" expand=user,manager
rippling list workers "filter=manager_id eq '<worker-id>'" expand=user
rippling list worker-changes "filter=updated_at gt '2026-10-01T00:00:00Z'"
rippling get departments <id>
rippling create leave-requests '{"worker_id":"<id>","leave_type_id":"<id>","start_date":"2026-11-02","end_date":"2026-11-03"}'
rippling api POST custom-objects/<api-name>/records/query '{"query":"SELECT * FROM ..."}'

Rippling sends customer webhooks only for custom-object records, so an automation that reacts to HR changes runs on a schedule and reads rippling list worker-changes for the window since its last run.

The developer-platform surfaces (apps, functions, packages, sandboxes, listings, and sites) are not reachable through this connector.