# Manage leave using the API

> For the complete documentation index, see [llms.txt](https://developer.rippling.com/llms.txt). Every page is available as Markdown by adding .md to its URL.

> List leave types, check balances, grant accruals, evaluate leave programs, and create/update leave requests using the Time Off APIs.

Source: https://developer.rippling.com/documentation/rest-api/guides/leave

## Overview

Rippling’s Time Off APIs let you read company leave types, inspect worker balances, grant or adjust accruals, evaluate statutory and custom leave programs, and create or update leave requests.

*Key terms:*

- **Leave type**: A company-configured category of time off (for example, Vacation or Sick). Use `leave_type_id` when creating requests or accruals.
- **Leave balance**: The worker’s remaining time off for a leave type, with and without future approved requests.
- **Leave accrual**: A credit or deduction applied to a worker’s balance (policy accrual, manual grant, correction, or payout). Accruals are the ledger behind a worker’s balance: automatic policy credits, manual grants, corrections, expirations, and payouts.
- **Leave program evaluation**: A rules-engine check that returns which statutory or custom leave programs apply to a proposed leave, plus any missing evidence.
- **Leave request**: A dated time-off request for a worker. Status is `PENDING`, `APPROVED`, `REJECTED`, or `CANCELED`.

### Available endpoints

| Endpoint | Description |
|----------|---------|
| [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md) | List company leave types. |
| [GET Retrieve a specific leave type](https://developer.rippling.com/documentation/rest-api/reference/get-leave-types.md) | Retrieve one leave type by `id`. |
| [GET List leave balances](https://developer.rippling.com/documentation/rest-api/reference/list-leave-balances.md) | List worker leave balances. |
| [GET Retrieve a specific leave balance](https://developer.rippling.com/documentation/rest-api/reference/get-leave-balances.md) | Retrieve one leave balance by `id`. |
| [GET List leave accruals](https://developer.rippling.com/documentation/rest-api/reference/list-leave-accruals.md) | List leave accrual records. |
| [GET Retrieve a specific leave accrual](https://developer.rippling.com/documentation/rest-api/reference/get-leave-accruals.md) | Retrieve one accrual by `id`. |
| [POST Create a new leave accrual](https://developer.rippling.com/documentation/rest-api/reference/create-leave-accruals.md) | Grant, deduct, or correct time off. |
| [POST Evaluate a leave program evaluation](https://developer.rippling.com/documentation/rest-api/reference/create-leave-program-evaluations) | Evaluate which leave programs apply to a proposed leave. |
| [GET List leave requests](https://developer.rippling.com/documentation/rest-api/reference/list-leave-requests.md) | List leave requests. |
| [GET Retrieve a specific leave request](https://developer.rippling.com/documentation/rest-api/reference/get-leave-requests.md) | Retrieve one leave request by `id`. |
| [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md) | Submit a leave request. |
| [PATCH Update a leave request](https://developer.rippling.com/documentation/rest-api/reference/update-leave-requests.md) | Edit a pending request, update comments, or change status (status must be a separate PATCH). |

Related endpoints:

| Endpoint | Description |
|----------|---------|
| [GET List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers.md) | Use the worker ID as the `role_id`. |

> **Endpoint notes:**
> - There is no delete endpoint for leave requests. Cancel a request by setting `status` to `CANCELED` on [PATCH Update a leave request](https://developer.rippling.com/documentation/rest-api/reference/update-leave-requests.md).
> - There is no endpoint to list leave policies. Use `leave_type_id` from [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md), and use `leave_policy_id` only when you already have a policy ID (for example, from an existing request).

### Suggested workflow

1. List [leave types](#leave-types) to get a valid `leave_type_id`.
2. Optionally [evaluate leave programs](#leave-program-evaluations) when the leave may be statutory (bonding, medical, pregnancy disability). Evaluation does not create a leave request.
3. If the evaluation returns `missing_evidence`, collect those answers and re-evaluate. Then create from `leave_plan.leave_request` using [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md).
4. Check [leave balances](#leave-balances) before creating PTO-style requests that deduct from a balance.
5. [Create a leave request](#create-a-leave-request). [Edit pending requests](#edit-a-leave-request) in place, [change status](#change-status) in a separate PATCH, and [cancel and recreate](#change-dates-on-approved-leave) to change dates on approved leave.
6. [Create a leave accrual](#create-a-leave-accrual) to grant time, apply a correction, or record a payout.

---

## Requirements

- The Rippling API SKU
- An API token with the following scopes:
  - `leave-types.read` to fetch leave types
  - `leave-balances.read` to fetch leave balances
  - `leave-accruals.read` to fetch leave accruals
  - `leave-accruals.read-write` to fetch and manage leave accruals
  - `leave-program-evaluations.read` to fetch leave program evaluations
  - `leave-program-evaluations.read-write` to fetch and manage leave program evaluations
  - `leave-requests.read` to fetch leave requests
  - `leave-requests.read-write` to fetch and manage leave requests

> **Rippling:**
> `leave-accruals.read-write` grants access to sensitive data and should be added with discretion.

---

## Fetch

### Leave types

Use [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md) to return a paginated list of company leave types. The `id` maps to `leave_type_id` on balances, accruals, and requests.

*Request:*

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

*Response:*

```json
{
  "results": [
    {
      "id": "65699295fb7bc7c3510f4075",
      "created_at": "2023-12-01T08:00:21.551000+00:00",
      "updated_at": "2025-04-20T13:50:50.632000+00:00",
      "type": "VACATION",
      "name": "Vacation",
      "description": "Paid vacation time",
      "is_paid": true,
      "is_managed_by_external_system": false
    }
  ],
  "next_link": null
}
```

| Response field | Description |
| ----- | ----------- |
| `type` | The category of leave. |
| `name` | Display name of the leave type. |
| `is_paid` | Whether time taken against this type is paid. |
| `is_managed_by_external_system` | Whether an external system owns this leave type. |

Use [GET Retrieve a specific leave type](https://developer.rippling.com/documentation/rest-api/reference/get-leave-types.md) to fetch a specific leave type when you already have the leave type `id`.

### Leave balances

Use [GET List leave balances](https://developer.rippling.com/documentation/rest-api/reference/list-leave-balances.md) to return a paginated list of balances for workers and leave types. Filter by `worker_id` when you need balances for a single employee.

*Request:*

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

*Response:*

```json
{
  "results": [
    {
      "id": "66a43405af71f094991bf950",
      "created_at": "2026-04-01T16:00:21.551000+00:00",
      "updated_at": "2026-06-01T15:04:21.551000+00:00",
      "worker_id": "6569928afb7bc7c3510f460f",
      "leave_type_id": "65699295fb7bc7c3510f4075",
      "is_balance_unlimited": false,
      "balance_including_future_requests": 64,
      "balance_excluding_future_requests": 80,
      "balance_including_future_requests_in_days": 8,
      "balance_excluding_future_requests_in_days": 10
    }
  ],
  "next_link": null
}
```

| Response field | Description |
| ----- | ----------- |
| `is_balance_unlimited` | When `true`, the numeric balance fields are null. |
| `balance_including_future_requests` | Remaining hours including future leave requests. |
| `balance_excluding_future_requests` | Remaining hours excluding future leave requests. |
| `balance_including_future_requests_in_days` | Remaining days including future leave requests. |
| `balance_excluding_future_requests_in_days` | Remaining days excluding future leave requests. |

Use [GET Retrieve a specific leave balance](https://developer.rippling.com/documentation/rest-api/reference/get-leave-balances.md) with the balance `id` to fetch a specific leave balance. Expand `worker` or `leave_type` when you need nested objects in the same response.

### Leave accruals

Use [GET List leave accruals](https://developer.rippling.com/documentation/rest-api/reference/list-leave-accruals.md) to return a paginated list of accrual records. Filter by `worker_id` or `leave_type_id` as needed.

*Request:*

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

*Response:*

```json
{
  "results": [
    {
      "id": "66b2512c4ad1db34abae1e82",
      "created_at": "2026-04-01T16:12:08.120000+00:00",
      "updated_at": "2026-04-01T16:12:08.120000+00:00",
      "worker_id": "6569928afb7bc7c3510f460f",
      "grantor_id": "65699281fb7bc7c3510f44a6",
      "leave_type_id": "65699295fb7bc7c3510f4075",
      "accrual_type": "LEAVE_GRANT",
      "accrual_date": "2026-04-01",
      "num_hours": 8,
      "comment": "Manual grant for unused holiday"
    }
  ],
  "next_link": null
}
```

Use [GET Retrieve a specific leave accrual](https://developer.rippling.com/documentation/rest-api/reference/get-leave-accruals.md) to fetch a single leave accrual.

### Leave requests

Use [GET List leave requests](https://developer.rippling.com/documentation/rest-api/reference/list-leave-requests.md) to return a paginated list of leave requests.

*Request:*

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

*Response:*

```json
{
  "results": [
    {
      "id": "66a43405af71f094991bf94f",
      "created_at": "2026-06-01T15:04:21.551000+00:00",
      "updated_at": "2026-06-01T15:04:21.551000+00:00",
      "worker_id": "6569928afb7bc7c3510f460f",
      "status": "PENDING",
      "start_date": "2026-06-01",
      "end_date": "2026-06-05",
      "leave_type_id": "65699295fb7bc7c3510f4075",
      "comments": "Family vacation",
      "number_of_minutes_requested": 2400,
      "days_take_off": [
        {
          "date": "2026-06-01",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-02",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-03",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-04",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-05",
          "number_of_minutes_taken_off": 480
        }
      ],
      "is_managed_by_external_system": false
    }
  ],
  "next_link": null
}
```

 Use [GET Retrieve a specific leave request](https://developer.rippling.com/documentation/rest-api/reference/get-leave-requests.md) to fetch a single leave request.

---

## Create

### Leave accrual

Use [POST Create a new leave accrual](https://developer.rippling.com/documentation/rest-api/reference/create-leave-accruals.md) to create a new leave accrual.

**Notes:**

- Grant time, apply a deduction, or record a payout with this endpoint.
- Negative `num_hours` or `num_days` values deduct from the balance.
- Send hours **or** days depending on how the policy tracks time.

*Request:*

```json
curl -L -X POST 'https://rest.ripplingapis.com/leave-accruals/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "worker_id": "6569928afb7bc7c3510f460f",
  "grantor_id": "65699281fb7bc7c3510f44a6",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "accrual_type": "LEAVE_GRANT",
  "accrual_date": "2026-04-01",
  "num_hours": 8,
  "comment": "Manual grant for unused holiday"
}
```

| Request body field | Required | Description |
| ----- | -------- | ----------- |
| `worker_id` | Yes | Worker (role ID) receiving the accrual. |
| `grantor_id` | Yes | Worker who granted the accrual (typically the Time Off admin). |
| `leave_type_id` | Yes | Company leave type from [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md). |
| `accrual_date` | Yes | Date the accrual becomes effective. |
| `accrual_type` | No | Source of the accrual. Common values include `AUTO`, `LEAVE_GRANT`, `BALANCE_CORRECTION_ADJUSTMENT`, `PAID_OUT`, and `WORKFLOW_ACTION`. See the [API reference](https://developer.rippling.com/documentation/rest-api/reference/create-leave-accruals.md) for the full enum. |
| `num_hours` | No | Hours accrued or deducted. Use when the policy tracks in hours. |
| `num_days` | No | Days accrued or deducted. Use when the policy tracks in days. |
| `monetary_amount_accrued` | No | Monetary value for policies with monetary tracking. |
| `expiration_date` | No | Date this accrual expires, if applicable. |
| `comment` | No | Required if the leave policy requires a comment on accruals. |

*Response:*

```json
{
  "id": "66b2512c4ad1db34abae1e82",
  "created_at": "2026-04-01T16:12:08.120000+00:00",
  "updated_at": "2026-04-01T16:12:08.120000+00:00",
  "worker_id": "6569928afb7bc7c3510f460f",
  "grantor_id": "65699281fb7bc7c3510f44a6",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "accrual_type": "LEAVE_GRANT",
  "accrual_date": "2026-04-01",
  "num_hours": 8,
  "comment": "Manual grant for unused holiday"
}
```

### Leave program evaluation

Use [POST Evaluate a leave program evaluation](https://developer.rippling.com/documentation/rest-api/reference/create-leave-program-evaluations) to see which statutory and custom leave programs apply to a proposed leave **before** you create a request. This is useful for parental leave, pregnancy disability, and medical leave, where eligibility depends on location, tenure, and evidence.

**Notes:**

- When `program_codes` is omitted, every registered leave program runs in dependency order.
- If the response includes `missing_evidence`, resubmit the evaluation with answers in `supplemental_evidence`.
- `role_id` is the worker’s role ID (the same value as `worker_id` on other Time Off endpoints).
- This call evaluates programs only. It does not create a leave request, an earnings input, or an accrual. The response is a recommendation, not a write.
- To book the proposed leave, match `leave_plan.leave_request.leave_type` to a company leave type from [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md), then [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md) with that type’s id as `leave_type_id`, the worker’s role ID as `worker_id`, and the plan’s `start_date`, `end_date`, and optional `status`.
- Apply `program_results[].directives` the same way when you intend to book them: a `leave_request` with [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md), `balance_adjustments` with [POST Create a new leave accrual](https://developer.rippling.com/documentation/rest-api/reference/create-leave-accruals.md), and earnings with [POST Create a new earnings input](https://developer.rippling.com/documentation/rest-api/reference/create-earnings-inputs).
- If `missing_evidence` is not empty, some validations can still be `UNKNOWN`. Resubmit the same evaluation with `supplemental_evidence`, using each `missing_evidence[].key` as the object key. Those answers only fill facts the evaluation reported as missing.
- `evidence_override` is for demo and test companies only. Do not send it in a production integration.

*Request:*

```json
curl -L -X POST 'https://rest.ripplingapis.com/leave-program-evaluations/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "role_id": "6569928afb7bc7c3510f460f",
  "leave_reason": "BONDING",
  "claim_start_date": "2026-06-01",
  "claim_end_date": "2026-08-24"
}
```

| Request body field | Required | Description |
| ----- | -------- | ----------- |
| `role_id` | Yes | Role ID of the employee whose leave should be evaluated. |
| `leave_reason` | Yes | One of `BONDING`, `PREGNANCY_DISABILITY`, `PREGNANCY_ACCOMMODATION`, `MEDICAL`, `VACATION`, or `OTHER`. |
| `claim_start_date` | Yes | Requested leave start date. |
| `claim_end_date` | No | Requested leave end date. When set, programs that publish pay rates can include estimated per-paycheck amounts. |
| `parental_leave_type` | No | Parental relationship type. Deprecated for most bonding evaluations; still accepted for backwards compatibility. |
| `birth_type` | No | `VAGINAL`, `C_SECTION`, or `UNKNOWN`. Used to estimate postpartum disability windows (for example, CA-SDI and CA-PDL). |
| `child_entered_family_date` | No | Date the child entered the family, for bonding programs. |
| `program_codes` | No | Limit evaluation to these program codes. |
| `supplemental_evidence` | No | Answers for evidence keys returned in `missing_evidence`. |
| `evidence_override` | No | Demo/test-company only. Overrides evidence to exercise eligibility scenarios. |

*Response:*

```json
{
  "program_results": [
    {
      "program_code": "CA-PFL",
      "eligibility": "eligible",
      "is_payable": true,
      "gaps": [],
      "program_validations": [
        {
          "validation_func": "employment_location",
          "outcome": "PASSED",
          "message": "Worker is in a covered location."
        }
      ],
      "directives": {
        "leave_request": {
          "leave_type": "BONDING",
          "start_date": "2026-06-01",
          "end_date": "2026-08-24",
          "status": "PENDING"
        },
        "earnings": [
          {
            "earning_type": "parental_leave",
            "amount": "1200.00",
            "currency": "USD"
          }
        ],
        "balance_adjustments": []
      }
    }
  ],
  "leave_plan": {
    "claim_start_date": "2026-06-01",
    "claim_end_date": "2026-08-24",
    "program_contributions": [
      {
        "program_code": "CA-PFL",
        "start_date": "2026-06-01",
        "end_date": "2026-08-24",
        "leave_type": "BONDING",
        "pay_status": "ESTIMATED"
      }
    ],
    "coverage_segments": [
      {
        "start_date": "2026-06-01",
        "end_date": "2026-08-24",
        "program_codes": ["CA-PFL"]
      }
    ],
    "pay_periods": [
      {
        "period_start": "2026-06-01",
        "period_end": "2026-06-15",
        "contributions": [
          {
            "program_code": "CA-PFL",
            "pay_source": "GOVERNMENT",
            "amount": {
              "amount": "1200.00",
              "currency": "USD"
            }
          }
        ],
        "total": {
          "amount": "1200.00",
          "currency": "USD"
        }
      }
    ],
    "leave_request": {
      "leave_type": "BONDING",
      "start_date": "2026-06-01",
      "end_date": "2026-08-24",
      "status": "PENDING"
    },
    "earnings": [
      {
        "earning_type": "parental_leave",
        "amount": "1200.00",
        "currency": "USD"
      }
    ],
    "balance_adjustments": []
  },
  "missing_evidence": [
    {
      "key": "child_entered_family_date",
      "label": "Date the child entered the family",
      "answer_type": "date",
      "program_codes": ["CA-PFL"]
    }
  ]
}
```

| Response field | Description |
| -------------- | ------- |
| `program_results` | Per-program rule output: `eligibility` (`eligible`, `ineligible`, `partially_eligible`), `is_payable`, validations, entitlements, pay rates, job protection, and `directives`. Each `directives` object can include a `leave_request`, payroll `earnings`, and `balance_adjustments`. |
| `leave_plan` | Combined plan from non-ineligible programs. Includes placement windows, coverage segments, optional `pay_periods` (when `claim_end_date` is set), a merged bookable `leave_request`, plus flattened `earnings` and `balance_adjustments`. `leave_request.leave_type` is the type to match when creating the request. |
| `missing_evidence` | Structured gaps. Each item has a stable `key`, `label`, `answer_type`, and the `program_codes` that need it. Resubmit those keys in `supplemental_evidence`. |

### Leave request

Use [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md) to create a new leave request. Provide either the `leave_type_id` or `leave_policy_id`.

**Notes:**

- For a partial day, send `start_time` and `end_time`, and/or `start_date_custom_hours` and `end_date_custom_hours`. Full-day requests need only `start_date` and `end_date`.
- When `is_managed_by_external_system` is `true`, another system owns the request or leave type. Treat those records as owned outside Rippling unless your integration is that system of record.

*Request:*

```json
curl -L -X POST 'https://rest.ripplingapis.com/leave-requests/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "PENDING",
  "start_date": "2026-06-01",
  "end_date": "2026-06-05",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "comments": "Family vacation"
}
```

| Request body field | Required | Description |
| ----- | -------- | ----------- |
| `worker_id` | Yes | Worker taking leave (role ID). |
| `status` | Yes | `PENDING`, `APPROVED`, `REJECTED`, or `CANCELED`. |
| `start_date` | Yes | First day of leave. |
| `end_date` | Yes | Last day of leave. |
| `leave_type_id` | Conditional | Leave type `id`. Required if `leave_policy_id` is omitted. |
| `leave_policy_id` | Conditional | Leave policy `id`. Required if `leave_type_id` is omitted. |
| `requester_id` | No | Worker who submitted the request, if different from `worker_id`. |
| `start_time` / `end_time` | No | Times for partial-day leave. |
| `start_date_custom_hours` / `end_date_custom_hours` | No | Hours off on the start or end date. |
| `comments` | No | Comments on the request. |
| `leave_event_id` | No | Associated leave event, if any. |
| `reason_for_leave` | No | Reason for the request. |
| `reviewer_id` / `reviewed_at` | No | Reviewer and review timestamp. |

*Response:*

```json
{
  "id": "66a43405af71f094991bf94f",
  "created_at": "2026-06-01T15:04:21.551000+00:00",
  "updated_at": "2026-06-01T15:04:21.551000+00:00",
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "PENDING",
  "start_date": "2026-06-01",
  "end_date": "2026-06-05",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "comments": "Family vacation",
  "number_of_minutes_requested": 2400,
  "days_take_off": [
        {
          "date": "2026-06-01",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-02",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-03",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-04",
          "number_of_minutes_taken_off": 480
        },
        {
          "date": "2026-06-05",
          "number_of_minutes_taken_off": 480
        }
  ],
  "is_managed_by_external_system": false
}
```

---

## Update

### Leave request

Use [PATCH Update a leave request](https://developer.rippling.com/documentation/rest-api/reference/update-leave-requests.md) to update an existing leave request.

**Notes:**

- Once a request is `APPROVED`, `REJECTED`, or `CANCELED`, only `comments` can be updated. Dates, policy, and other substantive fields cannot be changed in place.
- Do not change `status` in the same API call as other field updates.

*Request:*

```json
curl -L -X PATCH 'https://rest.ripplingapis.com/leave-requests/66a43405af71f094991bf94f/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "PENDING",
  "start_date": "2026-06-08",
  "end_date": "2026-06-12",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "comments": "Updated travel dates"
}
```

*Response:*

```json
{
  "id": "66a43405af71f094991bf94f",
  "created_at": "2026-06-01T15:04:21.551000+00:00",
  "updated_at": "2026-06-02T18:11:04.220000+00:00",
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "PENDING",
  "start_date": "2026-06-08",
  "end_date": "2026-06-12",
  "leave_type_id": "65699295fb7bc7c3510f4075",
  "comments": "Updated travel dates",
  "number_of_minutes_requested": 2400,
  "days_take_off": [
    {
      "date": "2026-06-08",
      "number_of_minutes_taken_off": 480
    },
    {
      "date": "2026-06-09",
      "number_of_minutes_taken_off": 480
    },
    {
      "date": "2026-06-10",
      "number_of_minutes_taken_off": 480
    },
    {
      "date": "2026-06-11",
      "number_of_minutes_taken_off": 480
    },
    {
      "date": "2026-06-12",
      "number_of_minutes_taken_off": 480
    }
  ],
  "is_managed_by_external_system": false
}
```

---

## Notifications

Notification behavior depends on how the leave request was created, how it is canceled, and the request’s status at the time of cancellation. Recipients (employee vs. employer/admin) can also differ. Integrations should not assume that API creates, edits, cancels, or recreates send the same notifications as the Rippling website.

| Action | Created via | Canceled / updated via | Status at the time of the action | Employee | Employer / admin |
| ------ | ----------- | ---------------------- | -------------------------------- | -------- | ---------------- |
| Create | API | — | `PENDING` | Sent when requester differs from employee; otherwise suppressed | Sent to first-stage approvers, excluding requester if also an approver |
| Create | API | — | `APPROVED` | Suppressed | Suppressed |
| Create | Website or other surface | — | Any | Normal flow: sent when requester differs from employee; external/import/EOR suppressed | Normal open requests: sent to first-stage approvers; external/import/EOR suppressed |
| Edit fields | Any | API | `PENDING` | No new notification | No new notification |
| Cancel | API, created with `status` = `APPROVED` | API | `APPROVED` | Suppressed | Suppressed |
| Cancel | API | API | `PENDING` | Sent when canceled by someone else; suppressed on self-cancel | Existing approver notifications updated; responders/watchers may be notified |
| Cancel | Website or other surface | Website, API, or other surface | Any | Normal flow: sent when canceled by someone else; external/EOR suppressed | On self-cancel, approval participants are notified or updated; on admin cancel, notification goes to employee; external/EOR suppressed |
| Create after cancel (new dates) | API | — | New request | If `PENDING`, sent when requester differs; if `APPROVED`, suppressed | If `PENDING`, first-stage approvers notified; if `APPROVED`, suppressed |

For leave requests created through the API directly in `APPROVED` status, cancellation notifications are suppressed when the request is canceled through the API. In that flow — created via API, canceled via API, canceled while `APPROVED` — users should not expect a cancellation notification.

“Employer / admin” refers to roles participating in the approval flow, not every company admin. “Sent” means Rippling generates a notification; final delivery remains subject to channel availability and notification settings.

---

## Use cases

### Change dates on approved leave

Approved leave dates cannot be edited in place. To change the dates on an approved leave request:

1. Cancel the existing request with a [status-only PATCH](#change-status) to `CANCELED`.
2. [Create a new leave request](#create-a-leave-request) with the updated dates.

### Change status

Status changes must be sent in a separate PATCH. You cannot combine a status change with other field edits in the same request.

Send `status` as the field you are changing. Include required `worker_id`, `start_date`, and `end_date` as the **current** values on the request; do not use that call to change dates, policy, comments, or other fields.

*Approve a pending request:*

```json
curl -L -X PATCH 'https://rest.ripplingapis.com/leave-requests/66a43405af71f094991bf94f/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "APPROVED",
  "start_date": "2026-06-01",
  "end_date": "2026-06-05"
}
```

*Cancel a request:*

```json
curl -L -X PATCH 'https://rest.ripplingapis.com/leave-requests/66a43405af71f094991bf94f/'
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer REDACTED'
```

*Request body:*

```json
{
  "worker_id": "6569928afb7bc7c3510f460f",
  "status": "CANCELED",
  "start_date": "2026-06-01",
  "end_date": "2026-06-05"
}
```

---

## FAQs

**Does evaluating a leave program create a leave request?**

No. [POST Evaluate a leave program evaluation](https://developer.rippling.com/documentation/rest-api/reference/create-leave-program-evaluations) returns eligibility and a proposed `leave_plan`. Create the request with [POST Create a new leave request](https://developer.rippling.com/documentation/rest-api/reference/create-leave-requests.md).

**Is `worker_id` the same as an employee ID?**

Use the worker’s Rippling **role ID** from [GET List workers](https://developer.rippling.com/documentation/rest-api/reference/list-workers.md). Program evaluations take that value as `role_id`. Do not send a user ID or employee number.

**Should I send `leave_type_id` or `leave_policy_id`?**

Send `leave_type_id` from [GET List leave types](https://developer.rippling.com/documentation/rest-api/reference/list-leave-types.md). One of `leave_type_id` or `leave_policy_id` is required. There is no public REST list-policies endpoint.

**Can I create a request already in `APPROVED` status?**

Yes. `status` on create accepts `PENDING`, `APPROVED`, `REJECTED`, or `CANCELED`. Use `APPROVED` when an admin or integration books leave that should not wait in a queue. Use `PENDING` when a manager still needs to review it.

**How do I approve, reject, or cancel a request?**

Send a [status-only PATCH](#change-status) with `status` set to `APPROVED`, `REJECTED`, or `CANCELED`. Do not combine that call with other field edits. Include required `worker_id`, `start_date`, and `end_date` as the current values. There is no DELETE.

**Can I change dates on an approved leave request?**

No. For `APPROVED`, `REJECTED`, or `CANCELED` requests, only `comments` can be edited in place. To change dates on approved leave, [cancel the request and create a new one](#change-dates-on-approved-leave).

**Do users get notified when the API creates or cancels leave?**

It depends on creation method, cancellation method, status, requester, and approval participants. Requests created through the API directly in `APPROVED` status do **not** send creation or cancellation notifications. Pending requests follow the requester and approver behavior described in [Notifications](#notifications).

**How do I request a partial day?**

Send `start_time` / `end_time` and/or `start_date_custom_hours` / `end_date_custom_hours`. The response `number_of_minutes_requested` and `days_take_off` show how Rippling converted that into minutes.

**Are leave balances in hours or days?**

Both. Hour fields are `balance_including_future_requests` and `balance_excluding_future_requests`. Day fields use the `_in_days` suffix. When `is_balance_unlimited` is `true`, the numeric fields are `null`.

**Why are including-future and excluding-future balances different?**

`balance_excluding_future_requests` is remaining time if future approved requests did not count. `balance_including_future_requests` subtracts those future requests. Use the including-future value when you need remaining time after already-booked leave.

**Does creating a leave request change the balance immediately?**

Balances are read-only. Approved future requests are reflected in `balance_including_future_requests`. To grant, deduct, or pay out time independently of a request, [create a leave accrual](#create-a-leave-accrual). Negative `num_hours` or `num_days` deduct from the balance. Send hours **or** days to match how the policy tracks time.

**What does `is_managed_by_external_system` mean?**

The leave type or request is owned by an external system. Filter or skip those records unless your integration is the system of record.

**How do I supply missing evidence for a program evaluation?**

Read `missing_evidence[].key` and `answer_type`. Resubmit the evaluation with `supplemental_evidence` as an object of those keys to answers. Use `gaps` on each program result for UNKNOWN evidence keys that still block a full eligibility decision.

**Do I need `claim_end_date` on an evaluation?**

`claim_start_date` is required. `claim_end_date` is optional. When it is set, `leave_plan.pay_periods` can include estimated per-paycheck amounts for programs that publish pay rates.

**When should I send `birth_type` or `child_entered_family_date`?**

Use `birth_type` (`VAGINAL`, `C_SECTION`, or `UNKNOWN`) for birthing-parent disability windows (for example, CA-SDI and CA-PDL). Use `child_entered_family_date` for bonding programs. `parental_leave_type` is deprecated for most bonding evaluations and is kept for older SDK callers.

**Which scopes do write operations need?**

Create or update requests: `leave-requests.read-write`. Create accruals: `leave-accruals.read-write`. Evaluate programs: `leave-program-evaluations.read-write`. Reads use the corresponding `.read` scopes. `leave-accruals.read-write` grants access to sensitive data.

**How do I watch for request changes without polling?**

App webhooks include `leave_request.created`, `leave_request.updated`, and `leave_request.deleted`. See [Webhooks](https://developer.rippling.com/documentation/developer-portal/v2-guides/webhooks.md). `leave_request.deleted` is sent when a request is deleted or canceled even though the REST API cancels via PATCH rather than DELETE.

---

## See also

- [Get started with the Time API](https://developer.rippling.com/documentation/rest-api/guides/time-getting-started.md)
- [Create and manage time entries](https://developer.rippling.com/documentation/rest-api/guides/create-time-entry.md)
- [API tokens and permissions](https://developer.rippling.com/documentation/rest-api/essentials/api-tokens.md)
- [Get started with webhooks](https://developer.rippling.com/documentation/rippling-platform/developer/webhooks/gettingstarted.md)