Deel: Create time-off request
Deel timeOff.createTimeOffRequest: arguments, response, policy and SDK examples.
← Time off operations · Get started
Operation deel.timeoff_createtimeoffrequest
Provider route: POST /time_offs. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/deel with npm, or alter-sdk-deel with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { DeelIntegration } from "@alter-ai/deel";
async function execute(input: Parameters<DeelIntegration["timeOff"]["createTimeOffRequest"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new DeelIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.timeOff.createTimeOffRequest(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_deel import DeelIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = DeelIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.time_off.create_time_off_request(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
body | object | Optional | |
body.data | Model | Optional | Expand Create time-off request — request body — body data The time off request data |
Referenced models: Create time-off request — request body — body data
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Create time-off request — 201 response body |
Referenced models: Create time-off request — 201 response body
Schemas
Section titled “Schemas”10 more schemas are linked from the tables above, on the schema pages.
Create time-off request — 201 response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The list of created time offs. Depending on the selected dates, a time off can be split into more than one request. |
time_offs | array | Required within parent | The list of created time offs. Depending on the selected dates, a time off can be split into more than one request. |
time_offs[] | Model | Each item | Expand Create time-off request — 201 response body — time offs item |
Referenced models: Create time-off request — 201 response body — time offs item
Create time-off request — request body — body data
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The time off request data |
contract_oid | string or null | Optional | Contract id. This is the id of the contract associated with the time off request. Maximum length: 24 |
custom_field_values | array or null | Optional | Answers to the custom fields the request policy declares, addressed by custom field id. |
custom_field_values[] | Model | Each item | Expand Create time-off request — request body — body data custom field values item |
dates | array | Optional | The dates breakdown for the time off request. |
dates[] | Model | Each item | Expand Create time-off request — request body — body data dates item |
deduction_amount | string or null | Optional | Deduction amount. Available for independent contractor's policies |
description | string or null | Optional | Description of the time off request. Some policies require that a description is provided. Maximum length: 500 |
end_date | Model | Required within parent | Expand Create time-off request — request body — body data end date End date of the time off request. This is the date when the time off ends. For example, if you take 2 days off, this will be the end date of the second day. |
event_details | Model | Optional | Expand Create time-off request — request body — body data event details Details of the event associated with the time off request. Required for event based policies such as parental leave. |
is_paid | boolean | Optional | Whether the time off is paid or unpaid. By default it follows the policy configuration. |
other_type_description | string or null | Optional | Description of the time off type. This is used when the policy is OTHER. Maximum length: 255 |
policy_id | string | Optional | The time off policy id. Can be used in place of time_off_type_id Format: uuid |
reason | string or null | Optional | Reason for taking time off. This is complementary information for the time-off description. Useful to provide sub categories for the same policy. Maximum length: 500 |
recipient_profile_id | string | Required within parent | The hris profile id of the recipient Format: uuid |
start_date | Model | Required within parent | Expand Create time-off request — request body — body data start date Start date of the time off request. This is the date when the time off starts. For example, if you take 2 days off, this will be the start date of the first day. |
status | string | Optional | Status for the time off request. When set to REQUESTED, the time off should be reviewed later through POST /time_offs/review. Default: APPROVED One of: REQUESTED, APPROVED |
time_off_event_id | string | Optional | The time off event id. This is used to link the time off request to an event. Format: uuid |
time_off_percentage | number or null | Optional | This is the percentage of time off taken. This is used when the time off request is a percentage. Format: double Maximum: 1 Minimum: 0 |
time_off_type_id | string | Optional | The time off type id. Required when policy_id is not provided Format: uuid |
use_deel_approval_flow | boolean | Optional | Whether to use Deel's approval flow for this time off request. If set to true, the time off request will go through Deel's approval flow instead of being handled through the public-api review time-off endpoint. Default: false |
Referenced models: Create time-off request — request body — body data custom field values item, Create time-off request — request body — body data dates item, Create time-off request — request body — body data end date, Create time-off request — request body — body data event details, Create time-off request — request body — body data start date
Create time-off request — request body — body data custom field values item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
field_id | string | Required within parent | The id of the custom field this value answers. Format: uuid |
value | JSON | Required within parent | The submitted value for the custom field. Accepts a string, number, or boolean — always stored as text. `null` means "no answer for this field" and is rejected today, since no field supports a null answer yet. |
value (oneOf 1) | Model | Alternative | Expand Create time-off request — request body — body data custom field values item value value |
value (oneOf 2) | null | Alternative |
Referenced models: Create time-off request — request body — body data custom field values item value value
Create time-off request — request body — body data dates item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The dates breakdown for the time off request. |
amount | string | Optional | The amount of time off requested for the date. It must be in the same time unit as in the total amount for the time off request. |
date | Model | Required within parent | Expand Create time-off request — request body — body data dates item date An specific date in the time-off request |
day_type | string | Optional | The type of day for the time off request. All dates must follow the same type. One of: HALF_DAY, FULL_DAY, PERCENTAGE, HOURLY |
hours | string | Optional | The amount taken in hours during this specific date. It can not exceed the maximum allowed hours for the date. |
Referenced models: Create time-off request — request body — body data dates item date
Create time-off request — request body — body data end date
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | End date of the time off request. This is the date when the time off ends. For example, if you take 2 days off, this will be the end date of the second day. |
$ (oneOf 1) | string | Alternative | Format: date |
$ (oneOf 2) | string | Alternative | Format: date-time |
Create time-off request — request body — body data event details
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Details of the event associated with the time off request. Required for event based policies such as parental leave. |
adoption_date | string | Optional | The date of adoption. This is used for parental leave requests. Format: date |
birth_date | string | Required within parent | The birth date of the child. This is used for parental leave requests. Format: date |
had_multiple_children | boolean | Required within parent | Whether the birth was multiple or not. This is used for parental leave requests. |
was_premature_birth | boolean | Required within parent | Whether the birth was premature or not. This is used for parental leave requests. |
Create time-off request — request body — body data start date
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | JSON | Root | Start date of the time off request. This is the date when the time off starts. For example, if you take 2 days off, this will be the start date of the first day. |
$ (oneOf 1) | string | Alternative | Format: date |
$ (oneOf 2) | string | Alternative | Format: date-time |
Update time-off request — 200 response body — time off custom field values item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
field_id | string | Required within parent | The id of the custom field this value answers. Format: uuid |
value | JSON | Required within parent | |
value (anyOf 1) | string | Alternative | The submitted value for the custom field, serialized as text. When no value is provided, this will be null. |
value (anyOf 2) | null | Alternative | The submitted value for the custom field, serialized as text. When no value is provided, this will be null. |
Update time-off request — 200 response body — time off attachments item
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | An attachment associated with the time off request. |
created_at | string | Required within parent | This is the date when the attachment was created in the database. Format: date-time |
filename | string | Required within parent | Filename of the attachment |
id | string | Required within parent | Attachment id Format: uuid |
updated_at | string | Required within parent | This is the date when the attachment was last updated in the database. Format: date-time |
Update time-off request — 200 response body — time off recipient profile
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | The time off profile of the recipient of the time off request. Must be a worker profile. |
hris_profile_id | string | Required within parent | The worker HRIS profile id in the given organization. Format: uuid |
organization_id | string | Required within parent | Id of the organization the profile belongs to. Format: uuid |
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: deel.timeoff_createtimeoffrequest. Catalog operation: timeoff_createtimeoffrequest. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Required provider scopes: ["time-off:write", "worker:write"]
Pinned headers: {"X-Version": "2026-01-01"}