> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.deel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.deel.com/_mcp/server.

# List time-off requests for Organization

GET https://api.letsdeel.com/rest/time_offs

Returns time-off requests for the authenticated organization, with optional filtering by status, date ranges, policy types, and specific request IDs. Results are paginated using cursor-based navigation.

 **Token scopes**: `time-off:read`

Reference: https://developer.deel.com/api/reference/endpoints/time-off/list-time-off-requests-for-organization-v-2026-01-01

## Authentication

- `Authorization` header (bearer token, required) — ## Authentication The Deel API uses bearer tokens to authenticate requests. All API calls must be made over HTTPS — calls over plain HTTP or without authentication will fail. ```curl curl -X GET 'https://api.letsdeel.com/rest/v2/contracts' \ -H 'Authorization: Bearer YOUR-TOKEN-HERE' ``` [Learn more about authentication](/api/authentication)
- `Authorization` header (bearer token, required) — Standard OAuth2 security scheme based on https://swagger.io/docs/specification/authentication/

## Servers

- `https://api.letsdeel.com/rest` (Production, default)
- `https://api-staging.letsdeel.com/rest` (Demo)

## Request

### Query parameters

- `status` (list of enum, optional) — Time off status
  - Allowed values: `REQUESTED`, `APPROVED`, `REJECTED`, `USED`, `CANCELED`, `DELETED`
- `time_off_ids` (list of string, optional) — Time off ids
- `start_date` (string, optional) — Start date of time off
- `end_date` (string, optional) — End date of time off
- `approval_start_date` (string, optional) — Approval start date
- `approval_end_date` (string, optional) — Approval end date
- `updated_start_date` (string, optional) — Updated start date
- `updated_end_date` (string, optional) — Updated end date
- `page_size` (integer, optional) — Page size
- `policy_types` (list of string, optional) — Policy types
- `policy_type_names` (list of enum, optional) — Filter by policy type names. When omitted, Work Location time-offs are excluded by default. Pass policy_type_names=Work+Location to retrieve only Work Location entries.
  - Allowed values: `Adoption leave`, `Advanced vacation`, `Bereavement leave`, `Blood donation leave`, `Breastfeeding leave`, `Childbirth leave`, `Childcare leave`, `Civic/public duty leave`, `Compensatory leave`, `Disability leave`, `Doctor's appointment leave`, `Family & domestic violence leave`, `Family responsibility leave`, `Floating Holiday Allowance`, `Hajj leave`, `Hospitalization leave`, `Long Service Leave`, `Marriage/wedding leave`, `Maternity leave`, `Menstrual leave`, `Military leave`, `Moving leave`, `Other leave`, `Paid leave`, `Parental leave`, `Paternity leave`, `Personal leave`, `Pregnancy leave`, `Regional holiday`, `RTT`, `Sick leave`, `Study leave`, `Supplementary Leave`, `Unpaid leave`, `Vacation`, `Vacation - public holidays replacement`, `Volunteer leave`, `Work accident leave`, `Work Location`
- `next` (string, optional) — Next page
- `include_deleted_time_offs` (boolean, optional, default: false) — When true, includes soft-deleted time-off records in the response. Deleted records will have a deleted_at timestamp and status DELETED.

## Response

### 200

Successful operation time offs returned

- `data` (list of TimeOffsGetResponsesContentApplicationJsonSchemaDataItems, required)
- `page_size` (integer, required) — Page size
- `has_next_page` (boolean, required) — Has next page
- `next` (string, optional)
- `count` (integer, optional) — Total count of items

## Errors

### 400 Bad Request Error

Bad request (invalid query parameters or validation error).

- `errors` (list of TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 401 Unauthorized Error

Unauthorized (missing or invalid token).

- `errors` (list of TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 403 Forbidden Error

Forbidden (insufficient permissions).

- `errors` (list of TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 404 Not Found Error

Not found (organization or HRIS profile not found).

- `errors` (list of TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems, required)

### 500 Internal Server Error

Internal server error.

- `errors` (list of TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems, required)

## Types

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItems

- `id` (string, required) — Time off id
- `amount` (float, required) — Amount of time off
- `is_paid` (boolean, required) — Is time off paid
- `end_date` (string, required) — End date of time off
- `created_at` (string, required) — Time off creation date
- `start_date` (string, required) — Start date of time off
- `updated_at` (string, required) — Time off update date
- `requested_at` (string, required) — Time off request date
- `half_end_date` (boolean, required) — Is half end date
- `half_start_date` (boolean, required) — Is half start date
- `entitlement_unit` (enum, required) — The unit in which the time off usage and entitlement are calculated.
  - Allowed values: `HOUR`, `BUSINESS_DAY`, `CALENDAR_DAY`, `WEEK`, `MONTH`, `YEAR`
- `time_off_type_id` (string, required) — Time off type id
- `reason` (string, optional) — Reason for time off
- `status` (enum, optional) — Status of time off
  - Allowed values: `REQUESTED`, `APPROVED`, `REJECTED`, `USED`, `CANCELED`, `DELETED`
- `deleted_at` (string, optional, nullable) — Time off deletion date. Present only when the time-off is soft-deleted and include_deleted_time_offs was requested.
- `approved_at` (string, optional, nullable) — Time off approval date
- `canceled_at` (string, optional, nullable) — Time off cancellation date
- `description` (string, optional, nullable) — Time off description
- `contract_oid` (string, optional) — Contract id
- `time_off_type` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffType, optional)
- `time_off_origin` (enum, optional) — Time off origin
  - Allowed values: `ADMIN`, `BULK_IMPORT`, `DEEL_APP`, `ENGAGE`, `INTEGRATION`, `PUBLIC_API`, `SLACK`, `TEAMS`, `UNKNOWN`
- `deduction_amount` (float, optional, nullable) — Deduction amount
- `time_off_dailies` (list of TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffDailiesItems, optional)
- `recipient_profile` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRecipientProfile, optional)
- `requester_profile` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRequesterProfile, optional)
- `time_off_percentage` (float, optional, nullable) — Time off percentage
- `is_end_date_estimated` (boolean, optional) — Is end date estimated
- `other_type_description` (string, optional, nullable) — Other type description

### TimeOffsGetResponsesContentApplicationJsonSchemaErrorsItems

- `code` (string, required)
- `message` (string, required)

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffType

- `id` (string, required) — Time off type id.
- `name` (string, required) — Time off type name. Basically the reason or category of time-off taken. For SICK leave, it can be doctor appointment, surgery etc.
- `policy` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffTypePolicy, optional)

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffDailiesItems

- `id` (string, required) — Time off daily id
- `date` (string, required) — Time off daily date
- `type` (enum, required) — Time off daily type
  - Allowed values: `WORKING_DAY`, `NON_WORKING_DAY`, `HOLIDAY`, `FORFAIT_HOUR_DAY`
- `amount` (float, required) — Time off daily amount
- `created_at` (string, required) — Time off daily creation date
- `updated_at` (string, required) — Time off daily update date
- `time_off_id` (string, required) — Time off id
- `description` (string, optional, nullable) — Time off daily description

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRecipientProfile

- `hris_profile_id` (string, optional) — Recipient hris profile id
- `organization_id` (string, optional) — Recipient organization id
- `client_profile_id` (string, optional) — Recipient client profile id

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRequesterProfile

- `hris_profile_id` (string, optional) — Request hris profile id
- `organization_id` (string, optional) — Request organization id
- `client_profile_id` (string, optional) — Request client profile id

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffTypePolicy

- `id` (string, required) — Policy id
- `name` (string, required) — The custom name given to policy during policy creation.
- `policy_type` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffTypePolicyPolicyType, required)

### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffTypePolicyPolicyType

- `id` (string, required) — Policy type id
- `name` (string, required) — Depicts the type of policy, like VACATION, SICK etc

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "amount": 0.5,
      "is_paid": true,
      "end_date": "2022-01-01",
      "created_at": "2022-01-01T00:00:00Z",
      "start_date": "2022-01-01",
      "updated_at": "2022-01-01T00:00:00Z",
      "requested_at": "2022-01-01",
      "half_end_date": true,
      "half_start_date": true,
      "entitlement_unit": "CALENDAR_DAY",
      "time_off_type_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
      "reason": "Vacation",
      "status": "REQUESTED",
      "deleted_at": "2022-01-01T00:00:00Z",
      "approved_at": "2022-01-01T00:00:00Z",
      "canceled_at": "2022-01-01T00:00:00Z",
      "description": "Vacation",
      "contract_oid": "32fk5ds",
      "time_off_type": {
        "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "name": "Vacation",
        "policy": {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "name": "Standard Vacation Policy",
          "policy_type": {
            "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
            "name": "Vacation"
          }
        }
      },
      "time_off_origin": "PUBLIC_API",
      "deduction_amount": 0.5,
      "time_off_dailies": [
        {
          "id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "date": "2022-01-01",
          "type": "WORKING_DAY",
          "amount": 0.5,
          "created_at": "2022-01-01T00:00:00Z",
          "updated_at": "2022-01-01T00:00:00Z",
          "time_off_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
          "description": "Vacation"
        }
      ],
      "recipient_profile": {
        "hris_profile_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "organization_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "client_profile_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
      },
      "requester_profile": {
        "hris_profile_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "organization_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
        "client_profile_id": "d290f1ee-6c54-4b01-90e6-d701748f0851"
      },
      "time_off_percentage": 0.5,
      "is_end_date_estimated": true,
      "other_type_description": "Vacation"
    }
  ],
  "page_size": 10,
  "has_next_page": true,
  "next": "string",
  "count": 100
}
```

**SDK Code**

```python
import requests

url = "https://api.letsdeel.com/rest/time_offs"

querystring = {"approval_end_date":"2022-01-01T00:00:00Z","approval_start_date":"2022-01-01T00:00:00Z","end_date":"2022-01-01T00:00:00Z","include_deleted_time_offs":"false","next":"d290f1ee-6c54-4b01-90e6-d701748f0851","page_size":"10","policy_type_names":"[\"Vacation\"]","policy_types":"[\"d290f1ee-6c54-4b01-90e6-d701748f0851\"]","start_date":"2022-01-01T00:00:00Z","status":"[\"REQUESTED\"]","time_off_ids":"[\"d290f1ee-6c54-4b01-90e6-d701748f0851\"]","updated_end_date":"2022-01-01T00:00:00Z","updated_start_date":"2022-01-01T00:00:00Z"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.letsdeel.com/rest/time_offs?approval_end_date=2022-01-01T00%3A00%3A00Z&approval_start_date=2022-01-01T00%3A00%3A00Z&end_date=2022-01-01T00%3A00%3A00Z&include_deleted_time_offs=false&next=d290f1ee-6c54-4b01-90e6-d701748f0851&page_size=10&policy_type_names=%5B%22Vacation%22%5D&policy_types=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&start_date=2022-01-01T00%3A00%3A00Z&status=%5B%22REQUESTED%22%5D&time_off_ids=%5B%22d290f1ee-6c54-4b01-90e6-d701748f0851%22%5D&updated_end_date=2022-01-01T00%3A00%3A00Z&updated_start_date=2022-01-01T00%3A00%3A00Z")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```