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

# Introduction

> Everything your own software needs to read your people, organisation and time off from andteam.

The andteam API is **read-only**. It gives another system the directory andteam holds: employees,
companies, the organisation's structure, positions, locations, lookups and approved time off. It
tells that system when a person joins, changes or leaves, by [signed webhooks](https://docs.andteam.com/guides/webhooks.md) or
by a feed you read. Create a key in your andteam console, point it at the base URL below, and every
endpoint is described in full in the [API reference](https://docs.andteam.com/api-reference/directory/list-employees.md).

## The basics

| | |
| - | - |
| Base URL | `https://api.v3.andteam.com/v1` |
| Authentication | `Authorization: Bearer atk_live_…`. See [Authentication](https://docs.andteam.com/authentication.md). |
| Format | JSON. Every refusal is `application/problem+json`. See [Errors](https://docs.andteam.com/errors.md). |
| Rate limit | 300 requests a minute per key, 1,200 a minute per tenant. See [Rate limits](https://docs.andteam.com/rate-limits.md). |
| Lists | `limit` (1 to 500) and an opaque `cursor`. See [Pagination](https://docs.andteam.com/pagination.md). |
| Version | `/v1`. See [Versioning](https://docs.andteam.com/versioning.md). |

## Make a first call

Your andteam administrator creates a key under **Settings**, **Integrations**, **API keys** in the
console at `https://{your-company}.andteam.com/admin/settings/tenant/integrations`. The secret is shown
once. Then:

```bash curl theme={null}
curl "https://api.v3.andteam.com/v1/employees?limit=2" \
  -H "Authorization: Bearer atk_live_…"
```

```python python theme={null}
import requests

r = requests.get(
    "https://api.v3.andteam.com/v1/employees",
    params={"limit": 2},
    headers={"Authorization": "Bearer atk_live_…"},
)
r.raise_for_status()
print(r.json()["data"])
```

```javascript javascript theme={null}
const res = await fetch("https://api.v3.andteam.com/v1/employees?limit=2", {
  headers: { Authorization: "Bearer atk_live_…" },
});
if (!res.ok) throw new Error(await res.text());
console.log((await res.json()).data);
```

```go go theme={null}
req, _ := http.NewRequest("GET", "https://api.v3.andteam.com/v1/employees?limit=2", nil)
req.Header.Set("Authorization", "Bearer atk_live_…")
res, err := http.DefaultClient.Do(req)
```

The answer is a page: `{ "data": [...], "next_cursor": "..." }`. A field the key may not read is
**left out, not sent as null**: see [Field groups](https://docs.andteam.com/concepts/field-groups.md).

## What the API never carries

ID or passport numbers, tax numbers, bank details, pay and pay history, health notes and sick
notes, performance, help questions and documents. They are not a field group and there is nothing to
switch on.

## The OpenAPI document

The OpenAPI document is at `GET /v1/openapi.json` on the API host. It needs no key. The reference
on this site is rendered from it, and you can generate a client from it.

## Before the first call

* [Authentication](https://docs.andteam.com/authentication.md): keys, companies, field groups, IP allow-list, expiry, roll and revoke.
* [Field groups](https://docs.andteam.com/concepts/field-groups.md): what each group opens, and why a field can be absent.
* [Pagination and syncing](https://docs.andteam.com/pagination.md): reading everything, then only what changed.
* [Webhooks](https://docs.andteam.com/guides/webhooks.md): verify every delivery before you act on it.


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