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

# Field groups

> What a key may read, and why a missing field is not a null one.

What a key reads is set by its **field groups**. They are chosen when the key is created (and for a
webhook endpoint, when its Include details switch is on) and decide which fields appear in every
response. A new key has Directory and Organisation.

| Group | Opens | Needs approval |
| - | - | - |
| **Directory** | `id`, `employeeNumber`, `firstName`, `preferredName`, `lastName`, `workEmail`, `workPhone`, `jobTitle`, `department`, `orgUnits`, `location`, `companyId`, `managerId`, `employmentType`, `status`, `startDate`, `lastDay`, `updatedAt`; and `GET /employees` and `GET /events` | No |
| **Organisation** | `GET /companies`, `GET /org-units`, `GET /locations` and `GET /lookups/{type}` | No |
| **Positions** | `positionNumber`, `positionTitle`, `reportsToPositionId` on an employee; `GET /positions` | No |
| **Time off** | `GET /time-off` | No |
| **Personal contact** | `personalEmail`, `mobile`, `homeAddress` | No |
| **Personal details** | `dateOfBirth`, `nationality`, `gender` | No |
| **Special categories** | `race`, `eeDesignation`, `disability`, `medicalAidMember` | Yes: [the Information Officer](https://docs.andteam.com/concepts/special-categories.md) |

## Absent, not null

A field the key may not read is **left out of the response. It is not sent as null.**

* A **missing** field means *not for you*: the key's groups do not open it.
* A **null** field means *no value*: the key may read it and andteam holds nothing.

The two are never the same, so a client can tell "this person has no personal email" from "this key
cannot see personal emails". Never treat a missing field as an empty value: that is how a sync
quietly overwrites a real value with nothing.

```json theme={null}
// A key with Directory only
{ "id": "emp_3kTq…", "firstName": "Thandi", "lastName": "Nkosi", "workEmail": null }

// The same person, a key that also holds Personal contact
{ "id": "emp_3kTq…", "firstName": "Thandi", "lastName": "Nkosi", "workEmail": null, "personalEmail": "thandi@example.com" }
```

The first has `workEmail: null`: the key may read it, there is none. It has no `personalEmail` at
all: the key may not.

## One rule for every route

The same groups govern an API key, a webhook endpoint's Include details and the person's own export of
"Systems that receive your data". An endpoint outside a key's groups answers
[`field-group-required`](https://docs.andteam.com/api/problems/field-group-required). A company outside a key's companies
answers [`company-not-allowed`](https://docs.andteam.com/api/problems/company-not-allowed).

## Events respect groups too

`changedFields` on an event names only fields the receiver's groups open. A receiver never learns that
a field outside its groups changed, not its value and not its name. An `employee.changed` whose every
changed field is outside a receiver's groups is **not sent to it at all**.

## New fields

A new field joins the group that fits it. A key never starts reading a group it was not given, so a
new field never reaches a system that was not entitled to it.

## What is in no group

ID or passport numbers, tax numbers, bank details, pay and pay history, health notes and sick notes,
performance, help questions and documents. There is nothing to switch on.


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