Leave

Requests, and the entitlement they draw on. Read a balance rather than deriving one: available_days accounts for accrual, and subtracting the raw columns over-reports every monthly-accrual policy. Policies and groups are read-only here — changing one retroactively changes what everyone is entitled to.

List leave types

GET/v1/leave_types

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
is_active	boolean	No	Filter by whether the record is in use.

Responses

Status	Meaning
200	A page of leave types.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Create a leave type

POST/v1/leave_types

Creates a leave type. code must be unique in the workspace.

A type on its own grants nothing — the entitlement lives on a policy, which is configured in the app.

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The resulting leave type.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	A leave type with that code already exists.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a leave type

GET/v1/leave_types/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The leave type.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave type in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Update a leave type

PATCH/v1/leave_types/{id}

Only the fields present in the body are changed.

Retiring a type is is_active: false, and there is no DELETE. Allocations and applications reference a leave type for ever, so one is never removed — a DELETE here would answer 200 and leave the record in place, which is worse than not offering it.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The updated leave type.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave type in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List leave policies

GET/v1/leave_policies

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
leave_type_id	string	No	Only records for this leave type.

Responses

Status	Meaning
200	A page of leave policies.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a leave policy

GET/v1/leave_policies/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The leave policy.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave policy in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List leave groups

GET/v1/leave_groups

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
is_active	boolean	No	Filter by whether the record is in use.

Responses

Status	Meaning
200	A page of leave groups.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a leave group

GET/v1/leave_groups/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The leave group.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave group in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

List leave balances

GET/v1/leave_balances

Query parameters

Name	Type	Required	Description
employee_id	string	Yes	Required. Balances are computed per employee.
fiscal_year_id	string	No	Defaults to the workspace's current fiscal year.

Responses

Status	Meaning
200	A page of leave balances.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

List leave applications

GET/v1/leave_applications

Query parameters

Name	Type	Required	Description
limit	integer	No	Page size. Values above 100 are clamped.
starting_after	string	No	Opaque cursor from a previous response’s next_cursor.
updated_since	timestamp	No	Return records changed at or after this instant. Tracks the record itself, not its child collections.
employee_id	string	No	Only records belonging to this employee.
leave_type_id	string	No	Only records for this leave type.
status	pending · approved · rejected · cancelled	No	Only requests in this state.
from_date	date	No	Requests OVERLAPPING this day or later. A request running 1–5 March matches a window starting on the 3rd.
to_date	date	No	Requests overlapping this day or earlier.

Responses

Status	Meaning
200	A page of leave applications.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
429	Rate limit exceeded. See the RateLimit-* headers.

Apply for leave

POST/v1/leave_applications

Applies on an employee's behalf.

total_days is computed by the workspace, not taken from the span: rest days, holidays and the sandwich rule all bear on it, so a five-day range may consume three days or seven.

Refused when the employee is ineligible under the policy (gender, tenure or employment type), when the balance is insufficient and the policy forbids a deficit, or when the dates overlap an existing request.

Headers

Name	Type	Required	Description
Idempotency-Key	string	No	A unique value per logical request. Replaying it returns the original response with Idempotent-Replay: true.

Responses

Status	Meaning
201	The resulting leave application.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
409	An overlapping leave request already exists for these dates.
429	Rate limit exceeded. See the RateLimit-* headers.

Retrieve a leave application

GET/v1/leave_applications/{id}

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The leave application.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave application in this workspace.
429	Rate limit exceeded. See the RateLimit-* headers.

Approve a leave application

POST/v1/leave_applications/{id}/approve

Consumes the balance and marks every day of the request as on_leave on the employee’s attendance. Answers 409 if the request was already decided.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The decided leave application.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave application in this workspace.
409	This request has already been decided.
429	Rate limit exceeded. See the RateLimit-* headers.

Reject a leave application

POST/v1/leave_applications/{id}/reject

Requires a reason in the body — it is the only thing the employee sees, and a rejection they cannot act on is not a decision. Answers 409 if the request was already decided.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The decided leave application.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave application in this workspace.
409	This request has already been decided.
429	Rate limit exceeded. See the RateLimit-* headers.

Cancel a leave application

POST/v1/leave_applications/{id}/cancel

Withdraws a request. An approved one can only be cancelled before it starts; cancelling it releases the balance and clears the attendance marks. Requires a reason.

Path parameters

Name	Type	Required	Description
id	string	Yes	The identifier returned as id on the object.

Responses

Status	Meaning
200	The decided leave application.
400	The request body failed validation.
401	The API key is missing, malformed, revoked or expired.
403	The key does not carry the required scopes.
404	No such leave application in this workspace.
409	This request has already been decided.
429	Rate limit exceeded. See the RateLimit-* headers.