Skip to content

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.

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 os
from alter_sdk import App
from 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()
FieldTypePresenceDescription and constraints
$objectRootAdditional keys: not allowed
bodyobjectOptional
body.dataModelOptionalExpand Create time-off request — request body — body data
The time off request data

Referenced models: Create time-off request — request body — body data

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

FieldTypePresenceDescription and constraints
$ModelRootExpand Create time-off request — 201 response body

Referenced models: Create time-off request — 201 response body

10 more schemas are linked from the tables above, on the schema pages.

Create time-off request — 201 response body
FieldTypePresenceDescription and constraints
$objectRootThe list of created time offs. Depending on the selected dates, a time off can be split into more than one request.
time_offsarrayRequired within parentThe list of created time offs. Depending on the selected dates, a time off can be split into more than one request.
time_offs[]ModelEach itemExpand 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
FieldTypePresenceDescription and constraints
$objectRootThe time off request data
contract_oidstring or nullOptionalContract id. This is the id of the contract associated with the time off request.
Maximum length: 24
custom_field_valuesarray or nullOptionalAnswers to the custom fields the request policy declares, addressed by custom field id.
custom_field_values[]ModelEach itemExpand Create time-off request — request body — body data custom field values item
datesarrayOptionalThe dates breakdown for the time off request.
dates[]ModelEach itemExpand Create time-off request — request body — body data dates item
deduction_amountstring or nullOptionalDeduction amount. Available for independent contractor's policies
descriptionstring or nullOptionalDescription of the time off request. Some policies require that a description is provided.
Maximum length: 500
end_dateModelRequired within parentExpand 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_detailsModelOptionalExpand 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_paidbooleanOptionalWhether the time off is paid or unpaid. By default it follows the policy configuration.
other_type_descriptionstring or nullOptionalDescription of the time off type. This is used when the policy is OTHER.
Maximum length: 255
policy_idstringOptionalThe time off policy id. Can be used in place of time_off_type_id
Format: uuid
reasonstring or nullOptionalReason 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_idstringRequired within parentThe hris profile id of the recipient
Format: uuid
start_dateModelRequired within parentExpand 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.
statusstringOptionalStatus 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_idstringOptionalThe time off event id. This is used to link the time off request to an event.
Format: uuid
time_off_percentagenumber or nullOptionalThis 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_idstringOptionalThe time off type id. Required when policy_id is not provided
Format: uuid
use_deel_approval_flowbooleanOptionalWhether 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
FieldTypePresenceDescription and constraints
$objectRoot
field_idstringRequired within parentThe id of the custom field this value answers.
Format: uuid
valueJSONRequired within parentThe 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)ModelAlternativeExpand Create time-off request — request body — body data custom field values item value value
value (oneOf 2)nullAlternative

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
FieldTypePresenceDescription and constraints
$objectRootThe dates breakdown for the time off request.
amountstringOptionalThe 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.
dateModelRequired within parentExpand Create time-off request — request body — body data dates item date
An specific date in the time-off request
day_typestringOptionalThe type of day for the time off request. All dates must follow the same type.
One of: HALF_DAY, FULL_DAY, PERCENTAGE, HOURLY
hoursstringOptionalThe 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
FieldTypePresenceDescription and constraints
$JSONRootEnd 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)stringAlternativeFormat: date
$ (oneOf 2)stringAlternativeFormat: date-time
Create time-off request — request body — body data event details
FieldTypePresenceDescription and constraints
$objectRootDetails of the event associated with the time off request. Required for event based policies such as parental leave.
adoption_datestringOptionalThe date of adoption. This is used for parental leave requests.
Format: date
birth_datestringRequired within parentThe birth date of the child. This is used for parental leave requests.
Format: date
had_multiple_childrenbooleanRequired within parentWhether the birth was multiple or not. This is used for parental leave requests.
was_premature_birthbooleanRequired within parentWhether the birth was premature or not. This is used for parental leave requests.
Create time-off request — request body — body data start date
FieldTypePresenceDescription and constraints
$JSONRootStart 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)stringAlternativeFormat: date
$ (oneOf 2)stringAlternativeFormat: date-time
Update time-off request — 200 response body — time off custom field values item
FieldTypePresenceDescription and constraints
$objectRoot
field_idstringRequired within parentThe id of the custom field this value answers.
Format: uuid
valueJSONRequired within parent
value (anyOf 1)stringAlternativeThe submitted value for the custom field, serialized as text. When no value is provided, this will be null.
value (anyOf 2)nullAlternativeThe 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
FieldTypePresenceDescription and constraints
$objectRootAn attachment associated with the time off request.
created_atstringRequired within parentThis is the date when the attachment was created in the database.
Format: date-time
filenamestringRequired within parentFilename of the attachment
idstringRequired within parentAttachment id
Format: uuid
updated_atstringRequired within parentThis 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
FieldTypePresenceDescription and constraints
$objectRootThe time off profile of the recipient of the time off request. Must be a worker profile.
hris_profile_idstringRequired within parentThe worker HRIS profile id in the given organization.
Format: uuid
organization_idstringRequired within parentId of the organization the profile belongs to.
Format: uuid

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"}

Official provider source

Report an issue with this page

Necessary

Required for sign-in, security, authorization, and remembering your choices.

Always active

Analytics

Helps us understand which product and documentation features are useful.

Performance diagnostics

Uses performance tracing and privacy-masked session replay to diagnose problems.

You can change these choices at any time from Cookie settings.