> ## 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. # File a new hire: a prefilled draft offer HR completes > Needs the Hires field group's Write switch. Files a prefilled DRAFT OFFER, never a starter: the candidate is added to andteam and HR opens their offer with everything you sent filled in, picks the contract type and sends it. The hiring decision and offer approvals run as usual, and the hire is final when the offer is signed (`employee.hired`). Follow it with `GET /v1/hires/{id}` or the `hire.status_changed` webhook. ID or passport numbers, race, disability and bank details are never accepted (`validation-failed`, code `not-accepted`): the candidate gives them in onboarding. The same `externalRef` again is 409 `duplicate-hire` with the existing hire's `existingId`. A personal email someone in andteam already holds is 409 `possible-rehire` (`existingId` is that person, when they are in one of the key's companies): nothing is written and HR decides. `position.new` is refused (`not-supported`) while the tenant manages positions: name a vacant `positionId`. The key's requester (or `requestedBy`) must be able to add people and write job details in the company, as for an offer in andteam. ## OpenAPI ````yaml /openapi.json post /hires 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: /hires: post: tags: - Hires summary: 'File a new hire: a prefilled draft offer HR completes' description: >- Needs the Hires field group's Write switch. Files a prefilled DRAFT OFFER, never a starter: the candidate is added to andteam and HR opens their offer with everything you sent filled in, picks the contract type and sends it. The hiring decision and offer approvals run as usual, and the hire is final when the offer is signed (`employee.hired`). Follow it with `GET /v1/hires/{id}` or the `hire.status_changed` webhook. ID or passport numbers, race, disability and bank details are never accepted (`validation-failed`, code `not-accepted`): the candidate gives them in onboarding. The same `externalRef` again is 409 `duplicate-hire` with the existing hire's `existingId`. A personal email someone in andteam already holds is 409 `possible-rehire` (`existingId` is that person, when they are in one of the key's companies): nothing is written and HR decides. `position.new` is refused (`not-supported`) while the tenant manages positions: name a vacant `positionId`. The key's requester (or `requestedBy`) must be able to add people and write job details in the company, as for an offer in andteam. operationId: postHires parameters: - name: Idempotency-Key in: header required: true description: >- Unique per request; reuse it only to retry the same request with the same body. Remembered 24 hours. schema: type: string maxLength: 255 - name: validate_only in: query description: >- `true`: answer 200 with what would happen (the approval steps and who they resolve to, the knock-ons), and write nothing. schema: type: boolean requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/HireRequest' responses: '200': description: >- `?validate_only=true`: whether it would be filed, and the duplicate that would stop it. Nothing is written. 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 Idempotent-Replayed: description: >- `true` when this is the stored answer to an earlier request with the same `Idempotency-Key`. schema: type: string content: application/json: schema: $ref: '#/components/schemas/HirePreview' '201': description: >- Filed: the candidate is in andteam with a draft offer for HR to complete. 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 Idempotent-Replayed: description: >- `true` when this is the stored answer to an earlier request with the same `Idempotency-Key`. schema: type: string content: application/json: schema: $ref: '#/components/schemas/Hire' '400': description: >- Invalid request. Problem types: `invalid-parameter`, `idempotency-key-missing`. headers: {} content: application/problem+json: schema: $ref: '#/components/schemas/Problem' '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' '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' '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' '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: HireRequest: type: object properties: companyId: type: string minLength: 1 maxLength: 80 description: One of the key's companies. candidate: type: object properties: firstName: type: string minLength: 1 maxLength: 100 description: Legal first name. lastName: type: string minLength: 1 maxLength: 100 description: Legal last name. preferredName: type: string minLength: 1 maxLength: 100 personalEmail: type: string maxLength: 320 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,}$ description: >- Where the offer and onboarding go. It must not belong to anyone already in andteam (`possible-rehire`). mobile: type: string pattern: ^\+?[0-9 ()-]{7,20}$ required: - firstName - lastName - personalEmail additionalProperties: false startDate: 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])))$ description: The start date the candidate was offered, company time. position: type: object properties: positionId: description: >- A vacant position of the company (`GET /v1/positions`, `vacant: true`). type: string minLength: 1 maxLength: 128 new: description: >- A job not yet in andteam. The offer makes its position when it is approved, as in the console. Refused while the tenant manages positions: then name a vacant `positionId`. type: object properties: jobTitle: type: string minLength: 1 maxLength: 200 description: A job title id or name from `GET /v1/lookups/job-titles`. orgUnitId: description: A unit from `GET /v1/org-units`. type: string minLength: 1 maxLength: 200 reportsToPositionId: description: >- The position the job reports to. Its holder is offered as the manager. type: string minLength: 1 maxLength: 128 locationId: description: A location from `GET /v1/locations`. type: string minLength: 1 maxLength: 128 employmentType: description: >- An employment type id or name, as an employee's `employmentType`. type: string minLength: 1 maxLength: 200 required: - jobTitle additionalProperties: false additionalProperties: false description: Exactly one of `positionId` or `new`. hiringManagerId: description: >- The hiring manager's employee id. Prefilled as the manager the job reports to. type: string minLength: 1 maxLength: 80 pay: description: >- The package the candidate was offered. HR reviews it in the offer, where the tenant's pay rules apply. type: object properties: basis: type: string enum: - monthly - annual - hourly currency: type: string pattern: ^[A-Z]{3}$ description: ISO 4217, such as ZAR. components: minItems: 1 maxItems: 50 type: array items: type: object properties: componentId: type: string minLength: 1 maxLength: 80 description: A component of the tenant's pay catalogue. values: type: object propertyNames: type: string additionalProperties: anyOf: - type: string maxLength: 500 - type: number - type: boolean description: >- The component's fields, by key, such as `{ "amount": 45000 }`. required: - componentId - values additionalProperties: false required: - basis - currency - components additionalProperties: false externalRef: type: object properties: system: type: string minLength: 1 maxLength: 80 description: Your system's name, such as `greenhouse`. id: type: string minLength: 1 maxLength: 200 description: The candidate's or application's id in that system. required: - system - id additionalProperties: false description: Your reference. The same reference again is `409 duplicate-hire`. 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. required: - companyId - candidate - startDate - position - externalRef additionalProperties: false HirePreview: type: object properties: wouldCreate: type: boolean duplicate: anyOf: - type: object properties: type: type: string enum: - duplicate-hire - possible-rehire existingId: description: >- The existing hire, or the person the email belongs to. Null for a person outside the key's companies. type: - string - 'null' required: - type - existingId additionalProperties: false - type: 'null' required: - wouldCreate - duplicate additionalProperties: false Hire: type: object properties: id: type: string status: type: string enum: - draft - awaiting_approval - approved - sent - signed - declined - withdrawn companyId: type: string employeeId: type: string description: >- The candidate's record. They are not an employee until the offer is signed (`employee.hired`). externalRef: type: object properties: system: type: string minLength: 1 maxLength: 80 description: Your system's name, such as `greenhouse`. id: type: string minLength: 1 maxLength: 200 description: The candidate's or application's id in that system. required: - system - id additionalProperties: false startDate: 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])))$ description: >- The start date the hire was filed with. The offer, once signed, sets the real one. consoleUrl: description: >- The offer wizard in andteam, opened on the candidate, for HR. Null when the tenant has no console address yet. type: - string - 'null' 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)))$ 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)))$ required: - id - status - companyId - employeeId - externalRef - startDate - consoleUrl - createdAt - 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 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.