Time off for rostering

Approved absences as dates, shown as Away, with the leave type never exposed.

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.