> ## Documentation Index
> Fetch the complete documentation index at: https://docs.andteam.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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.

```javascript theme={null}
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](https://docs.andteam.com/concepts/employee-events.md).
* A person's `status` of `left` or `upcoming` on `/employees` tells you whether they should be on the
  roster at all.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.