# Get started with the IT API

> Call the IT API to read app users, devices, orders, and software deployments.

## 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 endpoint | Required scopes | Schema | Notes / Requirements |
| --- | --- | --- | --- |
| [GET List app users](https://developer.rippling.com/documentation/rest-api/reference/list-app-users) | -   `app-users.read` | -   `AppUser`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific app user](https://developer.rippling.com/documentation/rest-api/reference/get-app-users) | -   `app-users.read` | -   `AppUser`<br>-   `MetaResponse` | -   Requires `id` from GET List app users. |

### Devices / Device Orders

| API endpoint | Required scopes | Schema | Notes / Prerequisites |
| --- | --- | --- | --- |
| [GET List devices](https://developer.rippling.com/documentation/rest-api/reference/list-devices) | -   `devices.read` | -   `Device`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific device](https://developer.rippling.com/documentation/rest-api/reference/get-devices) | -   `devices.read` | -   `Device`<br>-   `MetaResponse` | -   Requires `id` from GET List devices. |
| [GET List device orders](https://developer.rippling.com/documentation/rest-api/reference/list-device-orders) | -   `device-orders.read` | -   `DeviceOrder`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific device order](https://developer.rippling.com/documentation/rest-api/reference/get-device-orders) | -   `device-orders.read` | -   `DeviceOrder`<br>-   `MetaResponse` | -   Requires `id` from GET List device orders. |

### Software Deployments

| API endpoint | Required scopes | Schema | Notes / Prerequisites |
| --- | --- | --- | --- |
| [GET List software deployments](https://developer.rippling.com/documentation/rest-api/reference/list-software-deployments) | -   `software-deployments.read` | -   `SoftwareDeployment`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific software deployment](https://developer.rippling.com/documentation/rest-api/reference/get-software-deployments) | -   `software-deployments.read` | -   `SoftwareDeployment`<br>-   `MetaResponse` | -   Requires an `id` from GET List software deployments. |
| [POST Create a new software deployment](https://developer.rippling.com/documentation/rest-api/reference/create-software-deployments) | -   `software-deployments.read-write` | -   `SoftwareDeployment` | -   Requires a `software_id`, `group_id`, or `ma_device_group_id`. |
| [PATCH Update a software deployment](https://developer.rippling.com/documentation/rest-api/reference/update-software-deployments) | -   `software-deployments.read-write` | -   `SoftwareDeploymentUpdateRequest` | -   Requires an `id` from GET List software deployments. |
| [DELETE Delete a software deployment](https://developer.rippling.com/documentation/rest-api/reference/delete-software-deployments) | -   `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.

#### Example

![Talent Getting Started](https://developer.rippling.com/assets/images/gettingstartedguide2-7b37a3b054c1a404fb1af488fb2a1a49.png)

For more information on managing access using API tokens and permission profiles, see [API Tokens and Permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens).

* * *

## 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.

> **Note:**
> 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.

2.  Create an API token in the [Developer app](https://app.rippling.com/api-tokens/tokens) with the required scopes.
3.  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:_

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

_Response:_

```json
{
  "__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
}
```

Source: https://developer.rippling.com/documentation/rest-api/guides/it-getting-started

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Public pages have a Markdown version at the same URL with .md added.
