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	List company leave types.
GET Retrieve a specific leave type	Retrieve one leave type by id.
GET List leave balances	List worker leave balances.
GET Retrieve a specific leave balance	Retrieve one leave balance by id.
GET List leave accruals	List leave accrual records.
GET Retrieve a specific leave accrual	Retrieve one accrual by id.
POST Create a new leave accrual	Grant, deduct, or correct time off.
POST Evaluate a leave program evaluation	Evaluate which leave programs apply to a proposed leave.
GET List leave requests	List leave requests.
GET Retrieve a specific leave request	Retrieve one leave request by id.
POST Create a new leave request	Submit a leave request.
PATCH Update a leave request	Edit a pending request, update comments, or change status (status must be a separate PATCH).

Related endpoints:

Endpoint	Description
GET List workers	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.
• There is no endpoint to list leave policies. Use leave_type_id from GET List leave types, 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 to get a valid leave_type_id.
2. Optionally evaluate leave programs 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.
4. Check leave balances before creating PTO-style requests that deduct from a balance.
5. Create a leave request. Edit pending requests in place, change status in a separate PATCH, and cancel and recreate to change dates on approved leave.
6. 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

leave-accruals.read-write grants access to sensitive data and should be added with discretion.

---

Fetch

Leave types

Use GET List leave types to return a paginated list of company leave types. The id maps to leave_type_id on balances, accruals, and requests.

Request:

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

Response:

{
  "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 to fetch a specific leave type when you already have the leave type id.

Leave balances

Use GET List leave balances 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:

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

Response:

{
  "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 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 to return a paginated list of accrual records. Filter by worker_id or leave_type_id as needed.

Request:

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

Response:

{
  "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 to fetch a single leave accrual.

Leave requests

Use GET List leave requests to return a paginated list of leave requests.

Request:

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

Response:

{
  "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 to fetch a single leave request.

---

Create

Leave accrual

Use POST Create a new leave accrual 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:

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:

{
  "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.
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 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:

{
  "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 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, then POST Create a new leave request 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, balance_adjustments with POST Create a new leave accrual, and earnings with POST Create a new earnings input.
• 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:

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:

{
  "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:

{
  "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 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:

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:

{
  "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:

{
  "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 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:

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:

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

Response:

{
  "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 to CANCELED.
2. Create a new 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:

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:

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

Cancel a request:

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:

{
  "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 returns eligibility and a proposed leave_plan. Create the request with POST Create a new leave request.

Is worker_id the same as an employee ID?

Use the worker’s Rippling role ID from GET List workers. 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. 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 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.

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.

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. 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. 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
• Create and manage time entries
• API tokens and permissions
• Get started with webhooks