---
name: andteam
description: Use when integrating with the andteam read-only REST API (api.v3.andteam.com/v1) - reading employees, companies, org units, positions, locations, lookups and approved time off, syncing changes since a time, and receiving signed employee webhooks.
metadata:
  author: andteam
---

# andteam

andteam is an HR platform. Its REST API is **read-only**: it reads the directory andteam holds and
reports when a person joins, changes or leaves, by signed webhooks or a feed. The full documentation
is at [docs.andteam.com](https://docs.andteam.com/), and every endpoint is in the
[API reference](https://docs.andteam.com/api-reference/directory/list-employees).

**Base URL:** `https://api.v3.andteam.com/v1`

**Authentication:** `Authorization: Bearer atk_live_…`. A key holds companies and field groups, and
may carry an IP range and an expiry date. See [Authentication](https://docs.andteam.com/authentication).

## Endpoints

`GET /employees`, `GET /employees/{id}`, `GET /companies`, `GET /org-units`, `GET /positions`,
`GET /locations`, `GET /lookups/{type}` (`departments`, `cost-centres`, `grades`, `job-titles`),
`GET /time-off`, `GET /events` and `GET /openapi.json`. There is nothing else: no write endpoint.

## Concepts

- [Field groups](https://docs.andteam.com/concepts/field-groups): a key reads only the groups it holds. A field outside them is **absent, not null**: absent means "not for you", null means "no value".
- [Special categories](https://docs.andteam.com/concepts/special-categories): race, EE designation, disability and medical aid membership need a reason and the Information Officer's approval.
- [Pagination and syncing](https://docs.andteam.com/pagination): `limit` 1 to 500, opaque `cursor`, `next_cursor` null on the last page; read everything once, then read with `updated_since` set to when the last full read began.
- [Employee events](https://docs.andteam.com/concepts/employee-events): seven events, readable at `GET /events` and pushed by webhook.
- [The sandbox](https://docs.andteam.com/concepts/sandbox): a sandbox tenant creates no keys and no webhook endpoints.
- [Webhooks](https://docs.andteam.com/guides/webhooks): Standard Webhooks signing, a 5 minute tolerance, retries, at least once, not ordered.
- [Errors](https://docs.andteam.com/errors): RFC 9457 problem details; branch on `type`, never on `title` or `detail`.
- [Rate limits](https://docs.andteam.com/rate-limits): 300 a minute per key, a burst of 50 in 10 seconds, 1,200 a minute per tenant; `Retry-After` on a 429.
- [Versioning](https://docs.andteam.com/versioning): additive changes without notice; a breaking change is `/v2`, with `Deprecation` and `Sunset` headers on `/v1`.

## Rules that prevent real damage

- Ignore fields, event types and enum values you do not know.
- Verify every webhook's signature against the **raw body**, and the base64-**decoded** part of the `whsec_` secret is the HMAC key.
- Treat a webhook as at least once and not ordered: ignore an `id` already handled; drop an event older than the last `sequence` seen for that person.
- Page with the cursor the API returned. Never build or parse one.
- Wait for `Retry-After` on a 429: a refused request still counts.
- Time off is dates only, shown as Away. The leave type is never exposed.
- The API never carries ID numbers, tax numbers, pay, health notes, performance or documents. If an endpoint or field is not in the [API reference](https://docs.andteam.com/api-reference/directory/list-employees), the API does not serve it.