Skip to main content
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.

​
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.
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. A company outside a key’s companies answers 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.