FAfactorialhr
Timeoff > Leave

Creates a Leave

Changed on

Creates a Leave

post/api/2026-10-01/resources/timeoff/leaves

Request

  • Base URL
    https://api.factorialhr.com
  • URL
    https://api.factorialhr.com/api/2026-10-01/resources/timeoff/leaves
  • Auth
    • OAuth 2
      Authorization code: https://id.factorialhr.com/oauth/authorize
      Token URL: https://id.factorialhr.com/api/oauth/token scopes: time_off
    • or API key in header x-api-key

Request body

employee_idstring required

The employee id of the leave

leave_type_idstring

The leave type id

descriptionstring

The description of the leave

start_onstring required

The valid start date of the leave following the format YYYY-MM-DD

finish_onstring

The valid end date of the leave following the format YYYY-MM-DD

half_daystring

If the leave is in: [beggining_of_day, end_of_day]

start_timestring

The start time of a leave

hours_amount_in_centsinteger

The hours amount in cents of a leave

medical_leave_typeinteger

The medical leave type

effective_onstring

The effective on date of a leave following the format YYYY-MM-DD

medical_discharge_reasonstring

The medical discharge reason of a leave

colegiate_numberinteger

The colegiate number of a leave

has_previous_relapseboolean

If the leave has previous relapse

relapse_leave_idstring

The leave relapse id

relapse_onstring

The leave relapse on date following the format YYYY-MM-DD

accident_onstring

The leave accident on date following the format YYYY-MM-DD

paternity_birth_onstring

The leave paternity birth on date following the format YYYY-MM-DD

Example request

{
  "employee_id": "1",
  "leave_type_id": "36",
  "description": "Annual family vacation",
  "start_on": "2028-09-05",
  "finish_on": "2028-09-05",
  "start_time": "09:00",
  "effective_on": "2024-05-05",
  "medical_discharge_reason": "Illness",
  "colegiate_number": 150,
  "relapse_leave_id": "1",
  "relapse_on": "2028-09-05",
  "accident_on": "2028-09-05",
  "paternity_birth_on": "2028-09-05"
}

Response

CREATED

idstring required

Identifier of the Leave

company_idstring required

ID of the company the leave belongs to

employee_idstring required

ID of the employee taking the leave

start_onstring required

First day of the leave

finish_onstring

Last day of the leave (inclusive); null while an open-ended leave has no end yet

half_daystring

Which half of the day a half-day leave covers — beginning_of_day or end_of_day; null for full-day leaves

descriptionstring

Free-text description of the leave

reasonstring

The reason provided by the employee for taking the leave

leave_type_idstring

ID of the leave type this leave is of

leave_type_namestring

Denormalised name of the leave type

approvedboolean

Tri-state approval status — true = approved, false = rejected, null = pending approval

employee_full_namestring

The full name of the employee taking the leave

start_timestring

The start time of the leave

hours_amount_in_centsinteger

Total hours the leave consumes, in hundredths of an hour (e.g. 800 = 8 hours); set for hourly leaves

updated_atstring required

The updated at date of the leave

created_atstring

The created at date of the leave

deleted_atstring

The date when the leave was deleted

duration_attributesstring

The duration attributes of the leave

days_takennumber required

Number of days taken for paid leave. Reflects the summed per-day used total when the per-day breakdown is computed; otherwise the leave's calendar-day duration.

Example response

{
  "id": "1",
  "company_id": "1",
  "employee_id": "1",
  "start_on": "2028-09-05",
  "finish_on": "2028-09-05",
  "description": "Annual family vacation",
  "reason": "Medical appointment",
  "leave_type_id": "36",
  "approved": true,
  "employee_full_name": "Bob The Boss",
  "start_time": "09:00",
  "hours_amount_in_cents": 800,
  "updated_at": "2028-03-11T17:03:12.000Z",
  "created_at": "2028-03-11T17:03:12.000Z",
  "deleted_at": "2028-03-11T17:03:12.000Z",
  "days_taken": 1
}

Changes