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

# Employee events

> Seven events, written when a change takes effect, readable by feed and pushed by webhook.

When a person joins, changes or leaves, andteam records an **employee event**. Two things read the
same record: `GET /v1/events`, for a consumer that polls, and [webhooks](https://docs.andteam.com/guides/webhooks.md), for one
that listens.

| Event | Written when |
| - | - |
| `employee.hired` | The hire is final: the offer is signed, or a sync or import brought in a person with a start date. |
| `employee.started` | 00:00 on the start date, company time. |
| `employee.changed` | A change takes effect. `data.changedFields` names the fields. |
| `employee.leaving` | A termination is recorded. `data.lastDay` is the last day of work. |
| `employee.left` | Access has ended. |
| `employee.hire_withdrawn` | A hire was withdrawn before the start date. |
| `employee.termination_cancelled` | A recorded termination was cancelled. |

## Effective, not entered

A dated change, such as a start date or a job change on its effective date, is written **when it
takes effect, not when it was entered**. A promotion entered in January for 1 March is an event on
1 March. So an event is what is true now, and a consumer never has to hold a future change back.

## The outbox

Events are written to an outbox in the same step as the change itself, so a change that is made always
has its event, and an event never describes a change that was not made. Each event is then published
once it takes effect: `occurredAt` is when the change was recorded, `publishedAt` is when it took effect
and the event became readable.

## The feed

```bash theme={null}
curl "https://api.v3.andteam.com/v1/events?since=2027-03-18T00:00:00Z&type=employee.changed" \
  -H "Authorization: Bearer atk_live_…"
```

`since` filters on `publishedAt`. The feed pages like any other list: see
[Pagination](https://docs.andteam.com/pagination.md). It needs the Directory group, and `changedFields` names only fields the key's
groups open.

## Ordering and duplicates

Every event has an `id`, and a `sequence`: per person, in the order their changes took effect. Drop an
event older than the last `sequence` you saw for that person. Treat an `id` you have already handled
as handled. Both rules apply to a webhook receiver too.

## Thin, by default

An event carries ids, dates and the **names** of changed fields, never values. Read the record from the
API when you need it: it is always current, and it respects the key's groups. A webhook endpoint can
switch on Include details to receive the record with the event. See [Webhooks](https://docs.andteam.com/guides/webhooks.md).


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