# Get started with the Time API

> Authenticate, set permissions, and call Time API endpoints to access employee Time data in Rippling.

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

## Overview

Time APIs grant access to create and manage employee data within the Time product, which includes Schedules, Time & Attendance, Time Off, and Timeclock.

### Schedules

| API endpoint | Required scopes | Schema | Notes / Prerequisites |
| --- | --- | --- | --- |
| [GET List schedules](https://developer.rippling.com/documentation/rest-api/reference/list-schedules) | -   `schedules.read` | -   `Schedule`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific schedule](https://developer.rippling.com/documentation/rest-api/reference/get-schedules) | -   `schedules.read` | -   `Schedule`<br>-   `MetaResponse` | -   Requires `id` from GET List schedules. |
| [POST Create a new schedule](https://developer.rippling.com/documentation/rest-api/reference/create-schedules) | -   `schedules.read-write` | -   `Schedule`<br>-   `ScheduleRequest` |  |
| [PATCH Update a schedule](https://developer.rippling.com/documentation/rest-api/reference/update-schedules) | -   `schedules.read-write` | -   `Schedule`<br>-   `ScheduleRequest` | -   Requires `id` from GET List schedules. |
| [GET List shift assignments](https://developer.rippling.com/documentation/rest-api/reference/list-shiftassignments) | -   `shiftassignments.read` | -   `ShiftAssignment`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific shift assignment](https://developer.rippling.com/documentation/rest-api/reference/get-shiftassignments) | -   `shiftassignments.read` | -   `ShiftAssignment`<br>-   `MetaResponse` | -   Requires `id` from GET List shift assignments. |
| [POST Create a new shift assignment](https://developer.rippling.com/documentation/rest-api/reference/create-shiftassignments) | -   `shiftassignments.read-write` | -   `ShiftAssignment`<br>-   `ShiftAssignmentRequest` |  |
| [PATCH Update a shift assignment](https://developer.rippling.com/documentation/rest-api/reference/update-shiftassignments) | -   `shiftassignments.read-write` | -   `ShiftAssignment`<br>-   `ShiftAssignmentUpdateRequest` | -   Requires `id` from GET List shift assignments. |
| [PATCH Update custom fields for a shift assignment](https://developer.rippling.com/documentation/rest-api/reference/update-shiftassignments-customfields) | -   `shiftassignments.read-write` | -   `ShiftAssignment`<br>-   `MetaResponse` | -   Requires `id` from GET List shift assignments. |
| [GET List unassigned shifts](https://developer.rippling.com/documentation/rest-api/reference/list-unassignedshifts) | -   `unassignedshifts.read` | -   `UnassignedShift`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific unassigned shift](https://developer.rippling.com/documentation/rest-api/reference/get-unassignedshifts) | -   `unassignedshifts.read` | -   `UnassignedShift`<br>-   `MetaResponse` | -   Requires `id` from GET List unassigned shifts. |
| [POST Create a new unassigned shift](https://developer.rippling.com/documentation/rest-api/reference/create-unassignedshifts) | -   `unassignedshifts.read-write` | -   `UnassignedShift`<br>-   `UnassignedShiftRequest` |  |
| [PATCH Update an unassigned shift](https://developer.rippling.com/documentation/rest-api/reference/update-unassignedshifts) | -   `unassignedshifts.read-write` | -   `UnassignedShift`<br>-   `UnassignedShiftUpdateRequest` | -   Requires `id` from GET List unassigned shifts. |
| [PATCH Update custom fields for an unassigned shift](https://developer.rippling.com/documentation/rest-api/reference/update-unassignedshifts-customfields) | -   `unassignedshifts.read-write` | -   `UnassignedShift`<br>-   `MetaResponse` | -   Requires `id` from GET List unassigned shifts. |
| [POST Assign a worker to an unassigned shift](https://developer.rippling.com/documentation/rest-api/reference/assign-unassignedshifts) | -   `unassignedshifts.read-write` |  | -   Requires `id` from GET List unassigned shifts. |

### Time & Attendance

| API endpoint | Required scopes | Schema | Notes / Requirements |
| --- | --- | --- | --- |
| [GET List shift inputs](https://developer.rippling.com/documentation/rest-api/reference/list-shift-inputs) | -   `shift-inputs.read` | -   `ShiftInput`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific shift input](https://developer.rippling.com/documentation/rest-api/reference/get-shift-inputs) | -   `shift-inputs.read` | -   `ShiftInput`<br>-   `MetaResponse` | -   Requires `id` from GET List shift inputs. |
| [POST Create a new shift input](https://developer.rippling.com/documentation/rest-api/reference/create-shift-inputs) | -   `shift-inputs.read-write` | -   `ShiftInput`<br>-   `ShiftInputRequest` |  |
| [PATCH Update a shift input](https://developer.rippling.com/documentation/rest-api/reference/update-shift-inputs) | -   `shift-inputs.read-write` | -   `ShiftInput`<br>-   `ShiftInputRequest` | -   Requires `id` from GET List shift inputs. |
| [DELETE Delete a shift input](https://developer.rippling.com/documentation/rest-api/reference/delete-shift-inputs) | -   `shift-inputs.read-write` |  | -   Requires `id` from GET List shift inputs. |
| [GET List time cards](https://developer.rippling.com/documentation/rest-api/reference/list-time-cards) | -   `time-cards.read` | -   `TimeCard`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific time card](https://developer.rippling.com/documentation/rest-api/reference/get-time-cards) | -   `time-cards.read` | -   `TimeCard`<br>-   `MetaResponse` | -   Requires `id` from GET List time cards. |
| [GET List time entries](https://developer.rippling.com/documentation/rest-api/reference/list-time-entries) | -   `time-entries.read` | -   `TimeEntry`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific time entry](https://developer.rippling.com/documentation/rest-api/reference/get-time-entries) | -   `time-entries.read` | -   `TimeEntry`<br>-   `MetaResponse` | -   Requires `id` from GET List time entries. |
| [POST Create a new time entry](https://developer.rippling.com/documentation/rest-api/reference/create-time-entries) | -   `time-entries.read-write` | -   `TimeEntry`<br>-   `TimeEntryRequest` |  |
| [PATCH Update a time entry](https://developer.rippling.com/documentation/rest-api/reference/update-time-entries) | -   `time-entries.read-write` | -   `TimeEntry`<br>-   `TimeEntryRequest` | -   Requires `id` from GET List time entries. |
| [DELETE Delete a time entry](https://developer.rippling.com/documentation/rest-api/reference/delete-time-entries) | -   `time-entries.read-write` |  | -   Requires `id` from GET List time entries. |

### Time Off (Leave)

For a walkthrough of types, balances, accruals, program evaluations, and requests, see [Manage Leave Using the API](https://developer.rippling.com/documentation/rest-api/guides/leave).

| API endpoint | Required scopes | Schema | Notes / Prerequisites |
| --- | --- | --- | --- |
| [GET List leave accruals](https://developer.rippling.com/documentation/rest-api/reference/list-leave-accruals) | -   `leave-accruals.read` | -   `LeaveAccrual`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific leave accrual](https://developer.rippling.com/documentation/rest-api/reference/get-leave-accruals) | -   `leave-accruals.read` | -   `LeaveAccrual`<br>-   `MetaResponse` | -   Requires `id` from GET List leave accruals. |
| [POST Create a new leave accrual](https://developer.rippling.com/documentation/rest-api/reference/create-leave-accruals) | -   `leave-accruals.read-write` | -   `LeaveAccrual`<br>-   `LeaveAccrualRequest` |  |
| [GET List leave balances](https://developer.rippling.com/documentation/rest-api/reference/list-leave-balances) | -   `leave-balances.read` | -   `LeaveBalance`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific leave balance](https://developer.rippling.com/documentation/rest-api/reference/get-leave-balances) | -   `leave-balances.read` | -   `LeaveBalance`<br>-   `MetaResponse` | -   Requires `id` from GET List leave balances. |
| [GET List leave requests](https://developer.rippling.com/documentation/rest-api/reference/list-leave-requests) | -   `leave-requests.read` | -   `LeaveRequest`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific leave request](https://developer.rippling.com/documentation/rest-api/reference/get-leave-requests) | -   `leave-requests.read` | -   `LeaveRequest`<br>-   `MetaResponse` | -   Requires `id` from GET List leave requests. |
| [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests) | -   `leave-requests.read-write` | -   `LeaveRequest`<br>-   `LeaveRequestRequest` |  |
| [PATCH Update a leave request](https://developer.rippling.com/documentation/rest-api/reference/update-leave-requests) | -   `leave-requests.read-write` | -   `LeaveRequest`<br>-   `LeaveRequestRequest` | -   Requires `id` from GET List leave requests. |
| [POST Evaluate a leave program evaluation](https://developer.rippling.com/documentation/rest-api/reference/create-leave-program-evaluations) | -   `leave-program-evaluations.read-write` | -   `LeavePlanEvaluation` | -   Requires `role_id` from GET List workers. |
| [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types) | -   `leave-types.read` | -   `LeaveType`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific leave type](https://developer.rippling.com/documentation/rest-api/reference/get-leave-types) | -   `leave-types.read` | -   `LeaveType`<br>-   `MetaResponse` | -   Requires `id` from GET List leave types. |

### Timeclock

| API endpoint | Required scopes | Schema | Notes / Prerequisites |
| --- | --- | --- | --- |
| [GET List kiosk badges](https://developer.rippling.com/documentation/rest-api/reference/list-kiosk-badges) | -   `kiosk-badges.read` | -   `TimeKioskBadge`<br>-   `RedactedFields` |  |
| [GET Retrieve a specific kiosk badge](https://developer.rippling.com/documentation/rest-api/reference/get-kiosk-badges) | -   `kiosk-badges.read` | -   `TimeKioskBadge`<br>-   `MetaResponse` | -   Requires `id` from GET List kiosk badges. |
| [POST Create a new kiosk badge](https://developer.rippling.com/documentation/rest-api/reference/create-kiosk-badges) | -   `kiosk-badges.read-write` | -   `TimeKioskBadge`<br>-   `TimeKioskBadgeRequest` |  |
| [PATCH Update a kiosk badge](https://developer.rippling.com/documentation/rest-api/reference/update-kiosk-badges) | -   `kiosk-badges.read-write` | -   `TimeKioskBadge`<br>-   `TimeKioskBadgeRequest` | -   Requires `id` from GET List kiosk badges. |
| [DELETE Delete a kiosk badge](https://developer.rippling.com/documentation/rest-api/reference/delete-kiosk-badges) | -   `kiosk-badges.read-write` |  | -   Requires `id` from GET List kiosk badges. |

* * *

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

![Time 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 a Time 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.

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 schedules

_Request:_

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

_Response:_

```text
{
  "results": [
    {
      "id": "6927433ff50eaaf5e219a7dc",
      "created_at": "2025-11-26T18:13:19.735000+00:00",
      "updated_at": "2025-12-02T20:52:50.456000+00:00",
      "name": "AM Team",
      "managers_id": [],
      "observers_id": [],
      "members_id": [
        "6569930dfb7bc7c3510f5bac",
        "66a42da5d80b34a7fc92a3df"
      ],
      "managers": null,
      "observers": null,
      "members": null,
      "can_edit": true,
      "settings": {
        "timezone": "America/Los_Angeles"
      }
    }
  ],
  "next_link": null
}
```

* * *

## See also

-   [Create and Manage Time Entries](https://developer.rippling.com/documentation/rest-api/guides/create-time-entry)
-   [Rippling Time](https://help.rippling.com/?p=time)

Source: https://developer.rippling.com/documentation/rest-api/guides/time-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.