> ## 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. # Change an employee's personal and contact details > Needs the Directory field group. ## OpenAPI ````yaml /openapi.json patch /employees/{id} openapi: 3.1.0 info: title: andteam API version: 1.1.0 description: >- The andteam API: your people, organisation, leave, pay and records, and the changes other systems ask for. The key identifies the tenant; its companies and field groups decide what it reads and writes. ## 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. A sandbox tenant's keys start `atk_test_` and never read special categories, pay, documents or performance. An app installed in many tenants uses OAuth client credentials instead: it asks `POST /v1/oauth/token` for a one-hour `ato_…` token for one tenant and sends it the same way. A tenant's admin installs the app and chooses what it may read and write. ## 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. Writes have their own bucket inside those: 60 a minute per key. 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 | | 422 | [`validation-failed`](https://docs.andteam.com/api/problems/validation-failed) | The request body is not valid | | 409 | [`field-locked`](https://docs.andteam.com/api/problems/field-locked) | A field is owned by the HRIS for this person | | 403 | [`write-not-allowed`](https://docs.andteam.com/api/problems/write-not-allowed) | The API key may read this group but not write it | | 403 | [`requester-not-allowed`](https://docs.andteam.com/api/problems/requester-not-allowed) | The requester may not make this change | | 409 | [`approval-chain-unresolvable`](https://docs.andteam.com/api/problems/approval-chain-unresolvable) | A step of the approval chain resolves to nobody | | 409 | [`pending-change-exists`](https://docs.andteam.com/api/problems/pending-change-exists) | The person already has a change of this kind waiting | | 409 | [`duplicate-hire`](https://docs.andteam.com/api/problems/duplicate-hire) | A hire with this external reference already exists | | 409 | [`possible-rehire`](https://docs.andteam.com/api/problems/possible-rehire) | The candidate's personal email matches a current employee | | 400 | [`idempotency-key-missing`](https://docs.andteam.com/api/problems/idempotency-key-missing) | An Idempotency-Key header is required | | 422 | [`idempotency-key-reused`](https://docs.andteam.com/api/problems/idempotency-key-reused) | The Idempotency-Key was used with a different body | | 409 | [`idempotency-in-progress`](https://docs.andteam.com/api/problems/idempotency-in-progress) | A request with this Idempotency-Key is still running | | 428 | [`precondition-required`](https://docs.andteam.com/api/problems/precondition-required) | An If-Match header is required | | 412 | [`precondition-failed`](https://docs.andteam.com/api/problems/precondition-failed) | The record changed since the ETag was read | | 409 | [`not-withdrawable`](https://docs.andteam.com/api/problems/not-withdrawable) | The request can no longer be withdrawn | | 405 | [`method-not-allowed`](https://docs.andteam.com/api/problems/method-not-allowed) | The method is not allowed on this resource | | 415 | [`unsupported-media-type`](https://docs.andteam.com/api/problems/unsupported-media-type) | The body must be application/json | | 403 | [`test-key-not-allowed`](https://docs.andteam.com/api/problems/test-key-not-allowed) | A test key may not use this field group | ## Field groups What a key reads is set by its field groups: Directory, Organisation, Positions, Time off, Personal contact, Personal details, Special categories, Job history, Pay, Documents, Leave, Performance and Certifications. 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". Four groups need a written reason and a named approver, and are excluded until approved: Special categories and Documents (the Information Officer), Pay (whoever signs off payroll) and Performance (a performance admin). People in protected groups are left out of Pay and Performance unless the approver includes them. Health documents and sick notes are never served, and neither are ID numbers, tax numbers, bank details or help questions: there is nothing to switch on. An approval is for the scope it was given for. Widening a key's or endpoint's companies takes every approved group back to waiting for its approver, widening its document types does the same for Documents, and moving a webhook endpoint to a new address does the same for all of them; narrowing keeps the approval. A webhook delivery stored under an approval that has since changed is not sent: a retry fails with `approval_changed`, and Resend and Replay build the body again under the current approvals when the event is still one the endpoint takes. ## Writes A group with a write has a Write switch beside its Read switch: Personal contact, Personal details, Job history, Pay and Leave, and Hires, which is write-only. Every write is made for a named person, the key's requester (or `requestedBy` on the request, who is checked the same way), and runs through the same path as the console: the tenant's HRIS locks, approval chains, notifications and audit apply. A write never approves itself: - With an approval chain for the action, the answer is 202 with the pending request, and a `*.decided` webhook follows when the chain ends. - With no chain, the change applies at once (201), exactly as in the console. Every POST needs an `Idempotency-Key` header: a retry with the same key and body gets the first answer again (`Idempotent-Replayed: true`). Every PATCH needs `If-Match` with the record's `ETag`. Every create takes `?validate_only=true` to see what would happen, writing nothing. A body that is wrong is one 422 `validation-failed`, with every field's error in `errors`. The API never sends a letter: after an approved change, HR is asked to send it. ## 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.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 events to your endpoint: the employee events, and the request and record events (hires, job and pay changes, leave requests, released ratings, documents), each heard only with its group. 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: [] - oauth: [] 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: Job history description: A person's dated positions and terms. Needs the Job history field group. - name: Leave description: >- Leave types, balances and requests, named by type. A sick type is only ever `category: "sick"`, has no balance and no requests here. Needs the Leave field group. - name: Certifications description: >- Current certificates and qualifications. Needs the Certifications field group. - name: Hires description: >- New hires from an ATS, as draft offers HR completes. Needs the Hires field group's Write switch, which is write-only: it also reads the hires back. - name: Authentication description: OAuth client credentials for apps installed in many tenants. - 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: /employees/{id}: patch: tags: - Directory summary: Change an employee's personal and contact details description: Needs the Directory field group. operationId: patchEmployeesId parameters: - name: id in: path required: true description: The employee id. schema: type: string - name: company_id in: query description: One of the key's companies. schema: type: string - name: If-Match in: header required: true description: >- The `ETag` of the record as you read it. A stale one is 412 and nothing is written. schema: type: string requestBody: required: true content: application/merge-patch+json: schema: $ref: '#/components/schemas/EmployeePatch' responses: '200': description: Changed. The employee as the key reads it, with its new ETag. headers: RateLimit-Limit: description: Requests a minute allowed for the key. schema: type: integer RateLimit-Remaining: description: Requests left in the tightest window. schema: type: integer RateLimit-Reset: description: Seconds until that window resets. schema: type: integer Deprecation: description: Present once this version is deprecated (RFC 9745). schema: type: string Sunset: description: Present once this version has a shutdown date (RFC 8594). schema: type: string ETag: description: >- A strong validator of the record as this key sees it. Send it back as `If-Match`. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Employee' '401': description: >- No valid key. Problem types: `missing-key`, `invalid-key`, `revoked-key`, `expired-key`, `rolled-key-expired`. headers: WWW-Authenticate: description: Bearer realm="andteam" schema: type: string content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '403': description: >- Not allowed. Problem types: `pending-approval`, `ip-not-allowed`, `field-group-required`, `company-not-allowed`, `write-not-allowed`, `requester-not-allowed`, `test-key-not-allowed`. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '404': description: 'Not found. Problem types: `not-found`.' headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '409': description: >- Conflict. Problem types: `ambiguous-id`, `field-locked`, `approval-chain-unresolvable`, `pending-change-exists`, `duplicate-hire`, `possible-rehire`, `idempotency-in-progress`, `not-withdrawable`. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '412': description: 'Precondition failed. Problem types: `precondition-failed`.' headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '415': description: 'Unsupported media type. Problem types: `unsupported-media-type`.' headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '422': description: >- Not valid. Problem types: `validation-failed`, `idempotency-key-reused`. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '428': description: 'Precondition required. Problem types: `precondition-required`.' headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '429': description: 'Rate limited. Problem types: `rate-limited`.' headers: Retry-After: description: Seconds to wait before the next request. schema: type: integer content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '500': description: 'Server error. Problem types: `internal-error`.' headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' components: schemas: EmployeePatch: type: object properties: preferredName: description: Needs Personal details (Write). anyOf: - type: string maxLength: 100 - type: 'null' personalEmail: description: Needs Personal contact (Write). anyOf: - type: string format: email pattern: >- ^(?:[A-Za-z0-9_'+\-]+\.)*[A-Za-z0-9_'+\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ - type: 'null' mobile: description: Needs Personal contact (Write). Such as +27 82 555 0142. anyOf: - type: string maxLength: 20 - type: 'null' homeAddress: description: >- Needs Personal contact (Write). Merged part by part: a part sent as null is removed, a part left out is kept. anyOf: - type: object properties: line1: anyOf: - type: string maxLength: 200 - type: 'null' unitNumber: anyOf: - type: string maxLength: 200 - type: 'null' complexName: anyOf: - type: string maxLength: 200 - type: 'null' suburb: anyOf: - type: string maxLength: 200 - type: 'null' city: anyOf: - type: string maxLength: 200 - type: 'null' province: anyOf: - type: string maxLength: 200 - type: 'null' postalCode: anyOf: - type: string maxLength: 200 - type: 'null' country: anyOf: - type: string maxLength: 200 - type: 'null' additionalProperties: false - type: 'null' dateOfBirth: description: Needs Personal details (Write). anyOf: - type: string format: date pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$ - type: 'null' nationality: description: Needs Personal details (Write). ISO 3166 two-letter code. anyOf: - type: string pattern: ^[A-Z]{2}$ - type: 'null' requestedBy: type: string minLength: 1 maxLength: 320 description: >- Optional: the andteam user id or work email of the person this is requested by (the hiring manager in your ATS, say), instead of the key's requester. They are checked for the same permission over this employee; if the check fails the request is refused (requester-not-allowed), never put back on the key's requester. additionalProperties: false Employee: type: object properties: id: type: string description: The employee id. Stable for the life of the record. employeeNumber: type: - string - 'null' firstName: type: - string - 'null' preferredName: type: - string - 'null' lastName: type: - string - 'null' workEmail: type: - string - 'null' workPhone: type: - string - 'null' jobTitle: type: - string - 'null' department: type: - string - 'null' orgUnits: type: array items: $ref: '#/components/schemas/OrgUnitRef' description: >- The structure levels below Company that the person sits in, outermost first. location: type: - string - 'null' companyId: type: string description: >- The company that employs the person. Needs a key that holds this company. managerId: description: The manager's employee id, from the position the person holds. type: - string - 'null' employmentType: type: - string - 'null' status: type: string enum: - upcoming - active - left description: >- upcoming: the hire is final and the start date is ahead. active: started and not yet left. left: the last day has passed or access has ended. startDate: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' description: The first day of work, as a date in the company's time zone. lastDay: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' description: >- The last day of work, as a date in the company's time zone. Null until a termination is recorded. updatedAt: type: string format: date-time pattern: >- ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$ description: >- When any field of this record last changed. Use it with `updated_since`. positionNumber: type: - string - 'null' positionTitle: type: - string - 'null' reportsToPositionId: type: - string - 'null' personalEmail: type: - string - 'null' mobile: type: - string - 'null' homeAddress: anyOf: - $ref: '#/components/schemas/HomeAddress' - type: 'null' dateOfBirth: anyOf: - type: string pattern: ^\d{4}-\d{2}-\d{2}$ - type: 'null' nationality: type: - string - 'null' gender: type: - string - 'null' race: type: - string - 'null' eeDesignation: type: - string - 'null' disability: type: - boolean - 'null' medicalAidMember: type: - boolean - 'null' required: - id - employeeNumber - firstName - preferredName - lastName - workEmail - workPhone - jobTitle - department - orgUnits - location - companyId - managerId - employmentType - status - startDate - lastDay - updatedAt additionalProperties: false Problem: type: object properties: type: type: string description: >- A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}. title: type: string status: type: integer minimum: -9007199254740991 maximum: 9007199254740991 detail: type: string instance: type: string errors: description: 'validation-failed: every field that is wrong, at once.' type: array items: type: object properties: pointer: type: string description: >- A JSON Pointer (RFC 6901) to the field in the request body, such as /candidate/personalEmail. code: type: string description: >- A stable code for the error, such as required, invalid, insufficient-balance. detail: type: string required: - pointer - code - detail additionalProperties: false fields: description: >- field-locked: every field in the request the HRIS owns for this person. type: array items: type: string existingId: description: >- pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record. type: string step: description: 'approval-chain-unresolvable: the step that resolves to nobody.' type: string required: - type - title - status additionalProperties: false OrgUnitRef: type: object properties: level: type: string name: type: string required: - level - name additionalProperties: false HomeAddress: type: object properties: line1: type: - string - 'null' unitNumber: type: - string - 'null' complexName: type: - string - 'null' suburb: type: - string - 'null' city: type: - string - 'null' province: type: - string - 'null' postalCode: type: - string - 'null' country: type: - string - 'null' required: - line1 - unitNumber - complexName - suburb - city - province - postalCode - country additionalProperties: false securitySchemes: apiKey: type: http scheme: bearer bearerFormat: atk_live_… description: >- `Authorization: Bearer atk_live_…` (a sandbox's keys are `atk_test_…`). Created in the API keys section of the Integrations settings; the secret is shown once. oauth: type: oauth2 description: >- For an app installed in many tenants: client credentials, a one-hour `ato_…` token per tenant. flows: clientCredentials: tokenUrl: https://api.v3.andteam.com/v1/oauth/token scopes: {} ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.