> ## 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. # This document ## OpenAPI ````yaml /openapi.json get /openapi.json openapi: 3.1.0 info: title: andteam API version: 1.0.0 description: >- A read-only directory API. The key identifies the tenant; its companies and field groups decide what it reads. ## Authentication Send the key as a bearer token on every request: ``` Authorization: Bearer atk_live_… ``` An administrator creates keys in the API keys section of the Integrations settings. The secret is shown once, when the key is created or rolled. A key holds one or more companies and one or more field groups, and may carry an allowed IP range and an expiry date. When a key is rolled, the old secret keeps working for 24 hours. ## Rate limits Each key may make 300 requests a minute, with a burst of at most 50 in any 10 seconds. All the keys of one tenant together may make 1,200 a minute. Every response carries: - `RateLimit-Limit`: the key's requests a minute. - `RateLimit-Remaining`: what is left in the tightest window. - `RateLimit-Reset`: seconds until that window resets. Over the limit, the answer is 429 with `Retry-After` (seconds). A refused request still counts, so wait for `Retry-After` instead of retrying at once. ## Pagination Every list takes `limit` (1 to 500, default 100) and `cursor`, and answers `{ "data": [...], "next_cursor": "..." }`. Pass `next_cursor` as `cursor` to read the next page; it is null on the last page. There is no total and no offset. The cursor is opaque: do not build or parse one. Lists that change (employees, positions, time off, events) are read in the order records last changed, so a record that changes while you page moves to the end and is read again there: nothing is skipped. Small configuration lists (companies, locations, lookups, org units) page by id. To stay in step, read everything once, then read again with `updated_since` (or `since` for events) set to the time your last full read began. ## Errors Every refusal is `application/problem+json` (RFC 9457). Branch on `type`, a stable URL, never on `title` or `detail`. Each type has a page at its URL. | Status | Type | Meaning | | --- | --- | --- | | 401 | [`missing-key`](https://docs.andteam.com/api/problems/missing-key) | No API key was sent | | 401 | [`invalid-key`](https://docs.andteam.com/api/problems/invalid-key) | The API key is not valid | | 401 | [`revoked-key`](https://docs.andteam.com/api/problems/revoked-key) | The API key has been revoked | | 401 | [`expired-key`](https://docs.andteam.com/api/problems/expired-key) | The API key has expired | | 401 | [`rolled-key-expired`](https://docs.andteam.com/api/problems/rolled-key-expired) | The API key was rolled and its 24 hours are over | | 403 | [`pending-approval`](https://docs.andteam.com/api/problems/pending-approval) | The API key is waiting for the Information Officer's approval | | 403 | [`ip-not-allowed`](https://docs.andteam.com/api/problems/ip-not-allowed) | The request did not come from the key's allowed addresses | | 403 | [`field-group-required`](https://docs.andteam.com/api/problems/field-group-required) | The API key may not read this resource | | 403 | [`company-not-allowed`](https://docs.andteam.com/api/problems/company-not-allowed) | The API key may not read this company | | 429 | [`rate-limited`](https://docs.andteam.com/api/problems/rate-limited) | Too many requests | | 400 | [`invalid-parameter`](https://docs.andteam.com/api/problems/invalid-parameter) | A query parameter is not valid | | 404 | [`not-found`](https://docs.andteam.com/api/problems/not-found) | Not found | | 409 | [`ambiguous-id`](https://docs.andteam.com/api/problems/ambiguous-id) | More than one of the key's companies holds this id | | 500 | [`internal-error`](https://docs.andteam.com/api/problems/internal-error) | Something went wrong | ## Field groups What a key reads is set by its field groups: Directory, Organisation, Positions, Time off, Personal contact, Personal details and Special categories. A new key has Directory and Organisation. A field the key may not read is left out, not sent as null: a missing field means "not for you", a null field means "no value". Special categories (race and EE designation, disability, medical aid membership) need a written reason and the Information Officer's approval, and are excluded until then. The API never carries ID numbers, tax numbers, financial or pay details, health notes, performance, help questions or documents: there is nothing to switch on. ## Time off `/time-off` returns approved absences as dates, shown as **Away**. The leave type is never exposed, because a sick-leave day says something about health. An absence that was approved and then withdrawn or cancelled is returned with status `cancelled`, inside the `updated_since` window of its change, so you can remove it. ## Versioning This is version 1, at `/v1`. New fields, endpoints and event types are added without notice: ignore what you do not know. A breaking change is a new version, `/v2`, and `/v1` then answers with `Deprecation` (RFC 9745) and `Sunset` (RFC 8594) headers and keeps working for at least 12 more months. Every change is in the dated changelog: https://docs.andteam.com/api/changelog. ## Webhooks andteam can also push employee events to your endpoint. See the `webhooks` section of this document and the guide: https://docs.andteam.com/guides/webhooks. servers: - url: https://api.v3.andteam.com/v1 security: - apiKey: [] tags: - name: Directory description: Employees and the events about them. Needs the Directory field group. - name: Organisation description: >- Companies, structure levels, locations and lookups. Needs the Organisation field group. - name: Positions description: Positions and who they report to. Needs the Positions field group. - name: Time off description: Approved absences as dates, shown as Away. Needs the Time off field group. - name: Reference description: The API's own description. - name: Webhooks description: >- Events andteam POSTs to your endpoint. Signing, retries and verification: https://docs.andteam.com/guides/webhooks. paths: /openapi.json: get: tags: - Reference summary: This document operationId: openapi responses: '200': description: The OpenAPI 3.1 document content: application/json: schema: type: object security: [] components: securitySchemes: apiKey: type: http scheme: bearer bearerFormat: atk_live_… description: >- `Authorization: Bearer atk_live_…`. Created in the API keys section of the Integrations settings; the secret is shown once. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.