Time off for rostering

A rostering or scheduling tool needs to know one thing: who is away, and when. GET /v1/time-off answers exactly that and nothing more. It needs the Time off field group.

What it returns

Each item is one approved absence:

Field	Meaning
`id`	The absence id.
`employeeId`	The person. Match it to `id` on `/employees`.
`companyId`	The person’s company.
`from`, `to`	The first and last day away, as dates.
`halfDay`	Whether the absence is half a day.
`status`	`approved`, or `cancelled` once an approved absence is withdrawn or cancelled.
`updatedAt`	When the absence last changed.

The leave type is never exposed. A day of sick leave says something about a person’s health, so every absence is simply Away. Show it as that, and do not try to infer a type.

Reading it

Read it all once, then read only what changed:

curl "https://api.v3.andteam.com/v1/time-off?updated_since=2027-03-18T00:00:00Z" \
  -H "Authorization: Bearer atk_live_…"

An absence that was approved and then withdrawn or cancelled comes back with status: "cancelled", inside the updated_since window of its change. Remove it from your roster. Without that, a cancelled holiday stays on the board.

for (const a of await readAll(`/time-off?updated_since=${since}`, key)) {
  if (a.status === "cancelled") roster.remove(a.id);
  else roster.upsert(a.id, { who: a.employeeId, from: a.from, to: a.to, half: a.halfDay });
}

Pair it with GET /v1/employees?status=active for names and managers (Directory) so the roster can show who is away and tell a manager.

Tips

Filter with company_id when the roster covers one company. It must be one of the key’s companies.
Poll /time-off with updated_since. A rostering tool does not need a webhook: absences are not employee events.
A person’s status of left or upcoming on /employees tells you whether they should be on the roster at all.

Get started

Concepts

Guides

Problem types

Time off for rostering

What it returns

Reading it

Tips

​What it returns

​Reading it

​Tips

What it returns

Reading it

Tips