> This page is for API, version 2026-01-01 (Stable) (default). > For other versions, use one of these documentation indexes: > - 2026-01-01 (Stable) (default): https://developer.deel.com/api/stable/llms.txt > 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 across the entire authenticated organization; to list a single worker's requests, use GET /rest/time\_offs/profile/\{hris\_profile\_id} instead. Intended for bulk synchronization or auditing into an external HRIS, payroll, or reporting system. Only requests belonging to workers with an active primary employment are returned, and pending requests are included alongside approved and closed ones unless you filter by status. **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`, `Bereaved partner's paternity leave`, `Bereavement leave`, `Blood donation leave`, `Breastfeeding leave`, `Carer's 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`, `Neonatal care leave`, `Other leave`, `Paid leave`, `Parental bereavement leave`, `Parental leave`, `Paternity leave`, `Personal leave`, `Pregnancy leave`, `Regional holiday`, `RTT`, `Shared parental leave`, `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. AUTO_BANK_HOLIDAY is a bank holiday request that the system books for the worker. - Allowed values: `ADMIN`, `BULK_IMPORT`, `DEEL_APP`, `ENGAGE`, `INTEGRATION`, `PUBLIC_API`, `SLACK`, `TEAMS`, `AUTO_BANK_HOLIDAY`, `UNKNOWN` - `deduction_amount` (float, optional, nullable) — Deduction amount - `time_off_dailies` (list of TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsTimeOffDailiesItems, optional) - `recipient_profile` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRecipientProfile, optional) - `requester_profile` (TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsRequesterProfile, optional) - `custom_field_values` (list of TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsCustomFieldValuesItems, optional) — Answers to the custom fields the request policy declares. Omitted when the policy declares none. - `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 ### TimeOffsGetResponsesContentApplicationJsonSchemaDataItemsCustomFieldValuesItems - `value` (string, required, nullable) — The submitted value for the custom field, serialized as text. When no value is provided, this will be null. - `field_id` (string, required) — The id of the custom field this value answers. ### 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" }, "custom_field_values": [ { "value": "Family emergency", "field_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 "} 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 '}}; 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 ") 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 ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse 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 ") .asString(); ``` ```php 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 ', ], ]); 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 "); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] 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() ```