For AI agents: an index of this documentation is at https://developer.rippling.com/llms.txt. Public pages have a Markdown version at the same URL with .md added.

Skip to main content
guide

Get started with the IT API

Authenticate, set permissions, and call API endpoints to access IT data in Rippling.

Use with AI:Rippling AI ChatGPT Claude Cursor

Overview​

IT APIs offer access to app user, device, device orders, and software deployment information. This data can then be used to build custom automations, integrations, and reporting solutions within Rippling.

App Users​

API endpointRequired scopesSchemaNotes / Requirements
GET List app users
  • app-users.read
  • AppUser
  • RedactedFields
GET Retrieve a specific app user
  • app-users.read
  • AppUser
  • MetaResponse
  • Requires id from GET List app users.

Devices / Device Orders​

API endpointRequired scopesSchemaNotes / Prerequisites
GET List devices
  • devices.read
  • Device
  • RedactedFields
GET Retrieve a specific device
  • devices.read
  • Device
  • MetaResponse
  • Requires id from GET List devices.
GET List device orders
  • device-orders.read
  • DeviceOrder
  • RedactedFields
GET Retrieve a specific device order
  • device-orders.read
  • DeviceOrder
  • MetaResponse
  • Requires id from GET List device orders.

Software Deployments​

API endpointRequired scopesSchemaNotes / Prerequisites
GET List software deployments
  • software-deployments.read
  • SoftwareDeployment
  • RedactedFields
GET Retrieve a specific software deployment
  • software-deployments.read
  • SoftwareDeployment
  • MetaResponse
  • Requires an id from GET List software deployments.
POST Create a new software deployment
  • software-deployments.read-write
  • SoftwareDeployment
  • Requires a software_id, group_id, or ma_device_group_id.
PATCH Update a software deployment
  • software-deployments.read-write
  • SoftwareDeploymentUpdateRequest
  • Requires an id from GET List software deployments.
DELETE Delete a software deployment
  • software-deployments.read-write
  • Requires an id from GET List software deployments.

Permissions & scopes​

Rippling's V2 API uses a permissions-based access model. The data returned by an endpoint depends on:

  • The permission profile of the user who creates the API token. This includes the permission scope (e.g., “The entire company” vs. “Direct reports only”) and employment data access level (e.g., “View and edit all sensitive data” vs. “View all basic personal”).
  • The scopes selected when the token is created.

The Required Scopes for each endpoint are listed in the API reference documentation.

For more information on managing access using API tokens and permission profiles, see API Tokens and Permissions.


Call the API​

To call an IT API endpoint:

  1. Verify the user’s permission profile and ensure they have the permissions required to access the desired data.

If the user’s permissions are limited (for example, “Basic personal data for direct reports only”):

  • Some scopes will not be available when creating the API token.
  • The API response will return limited data.
  1. Create an API token in the Developer app with the required scopes.
  2. Call the endpoint using the generated token.

Some endpoints require a specific resource ID (for example, a worker_id). In these cases, call the corresponding list endpoint first to fetch the ID (e.g. call GET List workers before calling GET Retrieve a specific worker).

Example: GET List devices​

Request:

curl -L -X GET 'https://rest.ripplingapis.com/devices/' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer REDACTED'

Response:

{
"__meta": {
"redacted_fields": []
},
"results": [
{
"id": "66b26001a91aca1dfb199301",
"created_at": "2026-03-17T21:37:32.953000+00:00",
"updated_at": "2026-04-02T14:11:08.120000+00:00",
"serial_number": "C02YL0ABMD6M",
"worker_id": "58d3a1f0e4b0a12c3d456789",
"worker": null,
"platform": "MACOS",
"model": "MacBookPro18,3",
"os_name": "macOS",
"os_version": "15.3.1",
"lifecycle_state": "ACTIVE",
"enrollment_status": "ENROLLED",
"mdm_provider": "RIPPLING",
"is_managed": true,
"is_encrypted": true,
"last_checkin_at": "2026-04-02T14:05:00.000000+00:00",
"last_mdm_sync_at": "2026-04-02T13:40:00.000000+00:00",
"pending_actions_id": [],
"pending_actions": null
}
],
"next_link": null
}