Skip to main content
POST
Request leave for an employee

Authorizations

Authorization
string
header
required

Authorization: Bearer atk_live_… (a sandbox's keys are atk_test_…). Created in the API keys section of the Integrations settings; the secret is shown once.

Headers

Idempotency-Key
string
required

Unique per request; reuse it only to retry the same request with the same body. Remembered 24 hours.

Maximum string length: 255

Path Parameters

id
string
required

The employee id.

Query Parameters

company_id
string

One of the key's companies.

validate_only
boolean

true: answer 200 with what would happen (the approval steps and who they resolve to, the knock-ons), and write nothing.

Body

application/json
leaveTypeId
string
required

One of GET /v1/leave-types. A sick type is refused (sick-leave-in-portal).

Required string length: 1 - 100
startDate
string<date>
required

The first day, inclusive.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
endDate
string<date>
required

The last day, inclusive. Equal to startDate for a single day.

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
partOfDay
enum<string>

A half day: only with a single date, and only for a type counted in days.

Available options:
am,
pm
note
string

Shown to the approver. Never returned by the API.

Required string length: 1 - 1000
requestedBy
string

Optional: the andteam user id or work email of the person this is requested by (the hiring manager in your ATS, say), instead of the key's requester. They are checked for the same permission over this employee; if the check fails the request is refused (requester-not-allowed), never put back on the key's requester.

Required string length: 1 - 320

Response

?validate_only=true: what the request would be. Nothing was written.

wouldBe
enum<string>
required

approved when the leave approval chain has no steps.

Available options:
awaiting_approval,
approved
amount
number
required

What the request would use, in unit: working days, or hours for a type counted in hours.

unit
enum<string>
required
Available options:
days,
hours
balanceAfter
number | null
required

The balance left after this request, in unit. Only when andteam keeps the balance and the type has one; otherwise null.

steps
object[]
required

The approval chain, and who the current step resolves to.