> ## 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. # Get a pay change > Needs the Pay field group. Any pay change of the key's companies, filed through the API or in andteam: which components and from when, never an amount. ## OpenAPI ````yaml /openapi.json get /pay-changes/{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: /pay-changes/{id}: get: tags: - Pay summary: Get a pay change description: >- Needs the Pay field group. Any pay change of the key's companies, filed through the API or in andteam: which components and from when, never an amount. operationId: payChangesId parameters: - name: id in: path required: true description: The pay change id. schema: type: string responses: '200': description: OK 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/PayChange' '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' '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: PayChange: type: object properties: id: type: string employeeId: type: string companyId: type: string kind: type: string enum: - increase - promotion - adjustment effectiveDate: 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])))$ status: type: string enum: - awaiting_approval - approved - declined - withdrawn - applied - scheduled changedComponentIds: type: array items: type: string description: The components it changes. Never an amount. steps: type: array items: $ref: '#/components/schemas/ApprovalStep' requestedVia: anyOf: - type: object properties: keyId: type: string required: - keyId additionalProperties: false - type: 'null' description: The API key that filed it; null when it was made in andteam. createdAt: 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)))$ decidedAt: anyOf: - 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)))$ - type: 'null' required: - id - employeeId - companyId - kind - effectiveDate - status - changedComponentIds - steps - requestedVia - createdAt - decidedAt 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 ApprovalStep: type: object properties: id: type: string label: type: string approvers: type: array items: type: string status: type: string enum: - waiting - current - approved - declined required: - id - label - approvers - status 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.