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.
POST
/
hires
File a new hire: a prefilled draft offer HR completes
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.
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 string length: 1 - 320
Response
?validate_only=true: whether it would be filed, and the duplicate that would stop it. Nothing is written.
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"andteam","description":"The andteam API: your people, organisation, leave, pay and records, the changes other systems ask for, and signed webhooks.","colors":{"primary":"#00827B","light":"#30B3AB","dark":"#00827B"},"logo":{"light":"https://mintcdn.com/andteam/MVfTtzphnPhhxPa9/logo/andteam.svg?fit=max\u0026auto=format\u0026n=MVfTtzphnPhhxPa9\u0026q=85\u0026s=b11d93ffad90324a82a8c0d5d1a0c404","dark":"https://mintcdn.com/andteam/MVfTtzphnPhhxPa9/logo/andteam-dark.svg?fit=max\u0026auto=format\u0026n=MVfTtzphnPhhxPa9\u0026q=85\u0026s=b68c0b25cc90ff91d060372147b91013","href":"https://andteam.com"},"favicon":"https://mintcdn.com/andteam/MVfTtzphnPhhxPa9/logo/favicon.svg?fit=max\u0026auto=format\u0026n=MVfTtzphnPhhxPa9\u0026q=85\u0026s=5e85048315185eccf77ec4a1103b6ffc","api":{"openapi":"openapi.json","playground":{"display":"interactive"},"examples":{"defaults":"required","languages":["curl","python","javascript","go"],"prefill":true}},"background":{"color":{"light":"#F7F7F8","dark":"#0F1419"}},"navbar":{"primary":{"type":"button","label":"Get an API key","href":"https://andteam.com"}},"fonts":{"family":"Inter"},"icons":{"library":"lucide"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"andteam","hasAudioNarration":false,"actualSubdomain":"andteam","customDomains":["docs.andteam.com"],"gitSource":{"type":"github","owner":"hellocrowd","repo":"-team-v3","deployBranch":"main","contentDirectory":"docs-site","isPrivate":true,"mountPath":"","label":"","_id":"6af16e2a7af691b16ede1e0e"},"entitlements":{"AI_CHAT":{"status":"ENABLED"},"WEB_MCP":{"status":"ENABLED"},"NARRATION":{"status":"ENABLED"}},"buildId":"6af46cafec28eb92a90ad5d3","clientVersion":"0.0.4111","searchFilterCounts":[{"language":"default","tag":"Guides","count":59},{"language":"default","tag":"API reference","count":50},{"language":"default","tag":"Problem types","count":31},{"language":"default","tag":"Webhooks","count":16},{"language":"default","tag":"Get started","count":7},{"language":"default","tag":"Leave","count":6},{"language":"default","tag":"Concepts","count":5},{"language":"default","tag":"Job history","count":5},{"language":"default","tag":"Pay","count":5},{"language":"default","tag":"Directory","count":4}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":true,"hasWebMcpPermissions":true,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes","slug":"/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes","pageMetadata":{"title":"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.","deprecated":null,"version":null,"openapi":"/openapi.json post /hires","href":"/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx, jsxs: _jsxs} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n code: \"code\",\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsxs(_components.p, {\n children: [\"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 (\", _jsx(_components.code, {\n children: \"employee.hired\"\n }), \"). Follow it with \", _jsx(_components.code, {\n children: \"GET /v1/hires/{id}\"\n }), \" or the \", _jsx(_components.code, {\n children: \"hire.status_changed\"\n }), \" webhook. ID or passport numbers, race, disability and bank details are never accepted (\", _jsx(_components.code, {\n children: \"validation-failed\"\n }), \", code \", _jsx(_components.code, {\n children: \"not-accepted\"\n }), \"): the candidate gives them in onboarding. The same \", _jsx(_components.code, {\n children: \"externalRef\"\n }), \" again is 409 \", _jsx(_components.code, {\n children: \"duplicate-hire\"\n }), \" with the existing hire’s \", _jsx(_components.code, {\n children: \"existingId\"\n }), \". A personal email someone in andteam already holds is 409 \", _jsx(_components.code, {\n children: \"possible-rehire\"\n }), \" (\", _jsx(_components.code, {\n children: \"existingId\"\n }), \" is that person, when they are in one of the key’s companies): nothing is written and HR decides. \", _jsx(_components.code, {\n children: \"position.new\"\n }), \" is refused (\", _jsx(_components.code, {\n children: \"not-supported\"\n }), \") while the tenant manages positions: name a vacant \", _jsx(_components.code, {\n children: \"positionId\"\n }), \". The key’s requester (or \", _jsx(_components.code, {\n children: \"requestedBy\"\n }), \") must be able to add people and write job details in the company, as for an offer in andteam.\"]\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"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.","deprecated":null,"version":null,"openapi":"/openapi.json post /hires","href":"/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"operationId":"postHires","summary":"File a new hire: a prefilled draft offer HR completes","tags":["Hires"],"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.","parameters":["e50a2a1e-032a-47a9-8c5d-3ea19ffd38eb","ad10d5aa-f8de-4ae4-984f-a047ec990ad8"],"requestBody":"68f345fd-9454-41af-b072-67d9e5dd18fd","responses":{"200":"6e152fe3-b3cb-42ce-9a14-ba056f9223d4","201":"858a9abd-087d-41e6-965d-5881b0618da0","400":"96bb14cb-5846-4330-965b-bcbfd709895d","401":"61d1f21b-b833-4040-9354-fb67cdb46a4e","403":"72ea5181-4cc6-47d2-8494-f2776539c59f","409":"62427132-2769-43cd-9172-a203117d9500","415":"ec1eebef-9e6b-47b1-bfbb-ffe80cb9e4d8","422":"a4a4958b-1642-4c84-8e85-8764353d06d0","429":"c62b8dae-796b-4b57-b95e-75bcdbdaf8e0","500":"07e08eff-0cfb-4086-8fab-cdf7cba9faa8"},"method":"post","type":"path","servers":["53173e53-73ef-4ae2-87b8-83a71010e39d"],"security":["8176f727-c71c-46ea-9693-90364dc198f4","0c7e1611-cf8c-415a-bf94-31afa5ec5942"],"path":"/hires","baseUrlOptions":["https://api.v3.andteam.com/v1"],"title":"File a new hire: a prefilled draft offer HR completes","codeSamples":[],"requestExampleLanguages":["bash","python","javascript","go"],"requiredOnlyExamples":true,"requestExampleType":"generated","responseExampleType":"generated","prefillPlaygroundWithExample":true,"prefillPlaygroundExamples":[{"body.companyId":"\u003cstring>","body.candidate.firstName":"\u003cstring>","body.candidate.lastName":"\u003cstring>","body.candidate.personalEmail":"jsmith@example.com","body.candidate.preferredName":"\u003cstring>","body.candidate.mobile":"\u003cstring>","body.startDate":"2023-12-25","body.position.positionId":"\u003cstring>","body.externalRef.system":"\u003cstring>","body.externalRef.id":"\u003cstring>","body.hiringManagerId":"\u003cstring>","body.requestedBy":"\u003cstring>"}]},"dependencies":{"parameters":{"e50a2a1e-032a-47a9-8c5d-3ea19ffd38eb":{"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,"isRequired":true,"description":"Unique per request; reuse it only to retry the same request with the same body. Remembered 24 hours.","uniqueKey":"","typeLabel":"string"}},"ad10d5aa-f8de-4ae4-984f-a047ec990ad8":{"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","description":"`true`: answer 200 with what would happen (the approval steps and who they resolve to, the knock-ons), and write nothing.","uniqueKey":"","typeLabel":"boolean"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"companyId":{"type":"string","minLength":1,"maxLength":80,"description":"One of the key's companies.","isRequired":true,"uniqueKey":"companyId","typeLabel":"string"},"candidate":{"type":"object","properties":{"firstName":{"type":"string","minLength":1,"maxLength":100,"description":"Legal first name.","isRequired":true,"uniqueKey":"candidate.firstName","typeLabel":"string"},"lastName":{"type":"string","minLength":1,"maxLength":100,"description":"Legal last name.","isRequired":true,"uniqueKey":"candidate.lastName","typeLabel":"string"},"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`).","isRequired":true,"uniqueKey":"candidate.personalEmail","typeLabel":"string\u003cemail>"},"preferredName":{"type":"string","minLength":1,"maxLength":100,"uniqueKey":"candidate.preferredName","typeLabel":"string"},"mobile":{"type":"string","pattern":"^\\+?[0-9 ()-]{7,20}$","uniqueKey":"candidate.mobile","typeLabel":"string"}},"required":["firstName","lastName","personalEmail"],"additionalProperties":false,"isRequired":true,"uniqueKey":"candidate","typeLabel":"object"},"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.","isRequired":true,"uniqueKey":"startDate","typeLabel":"string\u003cdate>"},"position":{"type":"object","properties":{"positionId":{"description":"A vacant position of the company (`GET /v1/positions`, `vacant: true`).","type":"string","minLength":1,"maxLength":128,"uniqueKey":"position.positionId","typeLabel":"string"},"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`.","isRequired":true,"uniqueKey":"position.new.jobTitle","typeLabel":"string"},"orgUnitId":{"description":"A unit from `GET /v1/org-units`.","type":"string","minLength":1,"maxLength":200,"uniqueKey":"position.new.orgUnitId","typeLabel":"string"},"reportsToPositionId":{"description":"The position the job reports to. Its holder is offered as the manager.","type":"string","minLength":1,"maxLength":128,"uniqueKey":"position.new.reportsToPositionId","typeLabel":"string"},"locationId":{"description":"A location from `GET /v1/locations`.","type":"string","minLength":1,"maxLength":128,"uniqueKey":"position.new.locationId","typeLabel":"string"},"employmentType":{"description":"An employment type id or name, as an employee's `employmentType`.","type":"string","minLength":1,"maxLength":200,"uniqueKey":"position.new.employmentType","typeLabel":"string"}},"required":["jobTitle"],"additionalProperties":false,"uniqueKey":"position.new","typeLabel":"object"}},"additionalProperties":false,"description":"Exactly one of `positionId` or `new`.","isRequired":true,"uniqueKey":"position","typeLabel":"object"},"externalRef":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":80,"description":"Your system's name, such as `greenhouse`.","isRequired":true,"uniqueKey":"externalRef.system","typeLabel":"string"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"The candidate's or application's id in that system.","isRequired":true,"uniqueKey":"externalRef.id","typeLabel":"string"}},"required":["system","id"],"additionalProperties":false,"description":"Your reference. The same reference again is `409 duplicate-hire`.","isRequired":true,"uniqueKey":"externalRef","typeLabel":"object"},"hiringManagerId":{"description":"The hiring manager's employee id. Prefilled as the manager the job reports to.","type":"string","minLength":1,"maxLength":80,"uniqueKey":"hiringManagerId","typeLabel":"string"},"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"],"isRequired":true,"uniqueKey":"pay.basis","typeLabel":"enum\u003cstring>"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","description":"ISO 4217, such as ZAR.","isRequired":true,"uniqueKey":"pay.currency","typeLabel":"string"},"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.","isRequired":true,"uniqueKey":"pay.components.items.[INDEX].componentId","typeLabel":"string"},"values":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"oneOf":[{"type":"string","maxLength":500,"uniqueKey":"pay.components.items.[INDEX].values.additionalProperties.oneOf.0","typeLabel":"string"},{"type":"number","uniqueKey":"pay.components.items.[INDEX].values.additionalProperties.oneOf.1","typeLabel":"number"},{"type":"boolean","uniqueKey":"pay.components.items.[INDEX].values.additionalProperties.oneOf.2","typeLabel":"boolean"}],"uniqueKey":"pay.components.items.[INDEX].values.additionalProperties","typeLabel":"string | number | boolean"},"description":"The component's fields, by key, such as `{ \"amount\": 45000 }`.","isRequired":true,"uniqueKey":"pay.components.items.[INDEX].values","typeLabel":"object"}},"required":["componentId","values"],"additionalProperties":false,"uniqueKey":"pay.components.items.[INDEX]","typeLabel":"object"},"isRequired":true,"uniqueKey":"pay.components","typeLabel":"object[]"}},"required":["basis","currency","components"],"additionalProperties":false,"uniqueKey":"pay","typeLabel":"object"},"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.","uniqueKey":"requestedBy","typeLabel":"string"}},"required":["companyId","candidate","startDate","position","externalRef"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"companyId":"\u003cstring>","candidate":{"firstName":"\u003cstring>","lastName":"\u003cstring>","personalEmail":"jsmith@example.com","preferredName":"\u003cstring>","mobile":"\u003cstring>"},"startDate":"2023-12-25","position":{"positionId":"\u003cstring>"},"externalRef":{"system":"\u003cstring>","id":"\u003cstring>"},"hiringManagerId":"\u003cstring>","requestedBy":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"6e152fe3-b3cb-42ce-9a14-ba056f9223d4":{"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":{"type":"object","properties":{"wouldCreate":{"type":"boolean","isRequired":true,"uniqueKey":"wouldCreate","typeLabel":"boolean"},"duplicate":{"oneOf":[{"type":"object","required":["type","existingId"],"properties":{"type":{"type":"string","enum":["duplicate-hire","possible-rehire"],"isRequired":true,"uniqueKey":"duplicate.oneOf.0.type","typeLabel":"enum\u003cstring>"},"existingId":{"oneOf":[{"description":"The existing hire, or the person the email belongs to. Null for a person outside the key's companies.","type":"string","isRequired":true,"uniqueKey":"duplicate.oneOf.0.existingId.oneOf.0","typeLabel":"string"},{"description":"The existing hire, or the person the email belongs to. Null for a person outside the key's companies.","type":"null","isRequired":true,"uniqueKey":"duplicate.oneOf.0.existingId.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"duplicate.oneOf.0.existingId","typeLabel":"string | null"}},"additionalProperties":false,"isRequired":true,"uniqueKey":"duplicate.oneOf.0","typeLabel":"object"},{"type":"null","isRequired":true,"uniqueKey":"duplicate.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"duplicate","typeLabel":"object | null"}},"required":["wouldCreate","duplicate"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"wouldCreate":true,"duplicate":{"type":"duplicate-hire","existingId":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"858a9abd-087d-41e6-965d-5881b0618da0":{"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":{"type":"object","properties":{"id":{"type":"string","isRequired":true,"uniqueKey":"id","typeLabel":"string"},"status":{"type":"string","enum":["draft","awaiting_approval","approved","sent","signed","declined","withdrawn"],"isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"companyId":{"type":"string","isRequired":true,"uniqueKey":"companyId","typeLabel":"string"},"employeeId":{"type":"string","description":"The candidate's record. They are not an employee until the offer is signed (`employee.hired`).","isRequired":true,"uniqueKey":"employeeId","typeLabel":"string"},"externalRef":{"type":"object","properties":{"system":{"type":"string","minLength":1,"maxLength":80,"description":"Your system's name, such as `greenhouse`.","isRequired":true,"uniqueKey":"externalRef.system","typeLabel":"string"},"id":{"type":"string","minLength":1,"maxLength":200,"description":"The candidate's or application's id in that system.","isRequired":true,"uniqueKey":"externalRef.id","typeLabel":"string"}},"required":["system","id"],"additionalProperties":false,"isRequired":true,"uniqueKey":"externalRef","typeLabel":"object"},"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.","isRequired":true,"uniqueKey":"startDate","typeLabel":"string\u003cdate>"},"consoleUrl":{"oneOf":[{"description":"The offer wizard in andteam, opened on the candidate, for HR. Null when the tenant has no console address yet.","type":"string","isRequired":true,"uniqueKey":"consoleUrl.oneOf.0","typeLabel":"string"},{"description":"The offer wizard in andteam, opened on the candidate, for HR. Null when the tenant has no console address yet.","type":"null","isRequired":true,"uniqueKey":"consoleUrl.oneOf.1","typeLabel":"null"}],"isRequired":true,"uniqueKey":"consoleUrl","typeLabel":"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)))$","isRequired":true,"uniqueKey":"createdAt","typeLabel":"string\u003cdate-time>"},"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)))$","isRequired":true,"uniqueKey":"updatedAt","typeLabel":"string\u003cdate-time>"}},"required":["id","status","companyId","employeeId","externalRef","startDate","consoleUrl","createdAt","updatedAt"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":"\u003cstring>","status":"draft","companyId":"\u003cstring>","employeeId":"\u003cstring>","externalRef":{"system":"\u003cstring>","id":"\u003cstring>"},"startDate":"2023-12-25","consoleUrl":"\u003cstring>","createdAt":"2023-11-07T05:31:56Z","updatedAt":"2023-11-07T05:31:56Z"}}},"exampleType":"generated"}},"exampleType":"generated"},"96bb14cb-5846-4330-965b-bcbfd709895d":{"description":"Invalid request. Problem types: `invalid-parameter`, `idempotency-key-missing`.","headers":{},"content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"61d1f21b-b833-4040-9354-fb67cdb46a4e":{"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":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"72ea5181-4cc6-47d2-8494-f2776539c59f":{"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":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"62427132-2769-43cd-9172-a203117d9500":{"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":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"ec1eebef-9e6b-47b1-bfbb-ffe80cb9e4d8":{"description":"Unsupported media type. Problem types: `unsupported-media-type`.","headers":{},"content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"a4a4958b-1642-4c84-8e85-8764353d06d0":{"description":"Not valid. Problem types: `validation-failed`, `idempotency-key-reused`.","headers":{},"content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"c62b8dae-796b-4b57-b95e-75bcdbdaf8e0":{"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":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"},"07e08eff-0cfb-4086-8fab-cdf7cba9faa8":{"description":"Server error. Problem types: `internal-error`.","headers":{},"content":{"application/problem+json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"A stable URL for the kind of problem: https://docs.andteam.com/api/problems/{slug}.","isRequired":true,"uniqueKey":"type","typeLabel":"string"},"title":{"type":"string","isRequired":true,"uniqueKey":"title","typeLabel":"string"},"status":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"isRequired":true,"uniqueKey":"status","typeLabel":"integer"},"detail":{"type":"string","uniqueKey":"detail","typeLabel":"string"},"instance":{"type":"string","uniqueKey":"instance","typeLabel":"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.","isRequired":true,"uniqueKey":"errors.items.[INDEX].pointer","typeLabel":"string"},"code":{"type":"string","description":"A stable code for the error, such as required, invalid, insufficient-balance.","isRequired":true,"uniqueKey":"errors.items.[INDEX].code","typeLabel":"string"},"detail":{"type":"string","isRequired":true,"uniqueKey":"errors.items.[INDEX].detail","typeLabel":"string"}},"required":["pointer","code","detail"],"additionalProperties":false,"uniqueKey":"errors.items.[INDEX]","typeLabel":"object"},"uniqueKey":"errors","typeLabel":"object[]"},"fields":{"description":"field-locked: every field in the request the HRIS owns for this person.","type":"array","items":{"type":"string","uniqueKey":"fields.items.[INDEX]","typeLabel":"string"},"uniqueKey":"fields","typeLabel":"string[]"},"existingId":{"description":"pending-change-exists, duplicate-hire, possible-rehire: the id of the existing record.","type":"string","uniqueKey":"existingId","typeLabel":"string"},"step":{"description":"approval-chain-unresolvable: the step that resolves to nobody.","type":"string","uniqueKey":"step","typeLabel":"string"}},"required":["type","title","status"],"additionalProperties":false,"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"type":"\u003cstring>","title":"\u003cstring>","status":0,"detail":"\u003cstring>","instance":"\u003cstring>","errors":[{"pointer":"\u003cstring>","code":"\u003cstring>","detail":"\u003cstring>"}],"fields":["\u003cstring>"],"existingId":"\u003cstring>","step":"\u003cstring>"}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"8176f727-c71c-46ea-9693-90364dc198f4":{"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.","scopes":[],"schemeName":"apiKey"}},"0c7e1611-cf8c-415a-bf94-31afa5ec5942":{"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":{}}},"scopes":[],"schemeName":"oauth"}}},"servers":{"53173e53-73ef-4ae2-87b8-83a71010e39d":{"url":"https://api.v3.andteam.com/v1"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"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.","scopes":[],"schemeName":"apiKey"},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"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.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"apiKey","name":"Authorization"}],"title":"apiKey"},{"schemes":[{"scheme":{"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":{}}},"scopes":[],"schemeName":"oauth"},"schema":{"title":"OAuth2 Auth","type":"string","isRequired":true,"description":"For an app installed in many tenants: client credentials, a one-hour `ato_…` token per tenant.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"oauth","name":"Authorization"}],"title":"oauth"}]},"originalFileLocation":"openapi.json"},"subdomain":"andteam","siteName":"andteam","title":"File a new hire: a prefilled draft offer HR completes - andteam","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-11-11T08:45:03.455Z","originalFileLocation":"api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Needs the Hires field group\u0026#x27;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\u0026#x27;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\u0026#x27;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\u0026#x27;s requester (or requestedBy) must be able to add people and write job details in the company, as for an offer in andteam.\">\u003cmeta data-mint-head name=\"application-name\" content=\"andteam\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"File a new hire: a prefilled draft offer HR completes - andteam\">\u003cmeta data-mint-head property=\"og:description\" content=\"Needs the Hires field group\u0026#x27;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\u0026#x27;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\u0026#x27;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\u0026#x27;s requester (or requestedBy) must be able to add people and write job details in the company, as for an offer in andteam.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"andteam\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://andteam.mintlify.site/_mintlify/api/og/v2?division=Hires\u0026amp;title=File+a+new+hire%3A+a+prefilled+draft+offer+HR+completes\u0026amp;description=Needs+the+Hires+field+group%27s+Write+switch.+Files+a+prefilled+DRAFT+OFFER%2C+never+a+starter%3A+the+candidate+is+added+to+andteam+and+HR+opens+their+offer+with+ever\u0026amp;theme=823a7c0489dceecba2e0c789\u0026amp;signature=3c237645fd1d6fc46934cdd9718e92b91abe70b0723e4bb6cdc991e8b14a476e\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"File a new hire: a prefilled draft offer HR completes - andteam\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Needs the Hires field group\u0026#x27;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\u0026#x27;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\u0026#x27;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\u0026#x27;s requester (or requestedBy) must be able to add people and write job details in the company, as for an offer in andteam.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://andteam.mintlify.site/_mintlify/api/og/v2?division=Hires\u0026amp;title=File+a+new+hire%3A+a+prefilled+draft+offer+HR+completes\u0026amp;description=Needs+the+Hires+field+group%27s+Write+switch.+Files+a+prefilled+DRAFT+OFFER%2C+never+a+starter%3A+the+candidate+is+added+to+andteam+and+HR+opens+their+offer+with+ever\u0026amp;theme=823a7c0489dceecba2e0c789\u0026amp;signature=3c237645fd1d6fc46934cdd9718e92b91abe70b0723e4bb6cdc991e8b14a476e\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/andteam/D1YWVRbXj0UYh9MI/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"andteam\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#00827B\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/hires/file-a-new-hire%3A-a-prefilled-draft-offer-hr-completes.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.andteam.com/#organization\",\"name\":\"andteam\",\"url\":\"https://docs.andteam.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/andteam/MVfTtzphnPhhxPa9/logo/andteam.svg?fit=max\u0026auto=format\u0026n=MVfTtzphnPhhxPa9\u0026q=85\u0026s=b11d93ffad90324a82a8c0d5d1a0c404\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.andteam.com#website\",\"name\":\"andteam\",\"url\":\"https://docs.andteam.com\",\"publisher\":{\"@id\":\"https://docs.andteam.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes#webpage\",\"url\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes\",\"name\":\"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.\",\"dateModified\":\"2026-11-11T08:45:03.455Z\",\"isPartOf\":{\"@id\":\"https://docs.andteam.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"andteam\",\"item\":\"https://docs.andteam.com\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"File a new hire: a prefilled draft offer HR completes\",\"item\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes#apireference\",\"headline\":\"File a new hire: a prefilled draft offer HR completes\",\"name\":\"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.\",\"url\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes\",\"mainEntityOfPage\":{\"@id\":\"https://docs.andteam.com/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes#webpage\"},\"dateModified\":\"2026-11-11T08:45:03.455Z\",\"publisher\":{\"@id\":\"https://docs.andteam.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.andteam.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"andteam\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"andteam\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference/hires/file-a-new-hire%3A-a-prefilled-draft-offer-hr-completes.md","siteName":"andteam","nav":{"global":null,"tabs":[{"tab":"Guides","pages":[{"title":"Guides","href":""}]},{"tab":"API reference","groups":[{"group":"Directory","pages":[{"title":"List employees","deprecated":null,"version":null,"openapi":"/openapi.json get /employees","href":"/api-reference/directory/list-employees"},{"title":"Get one employee","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}","href":"/api-reference/directory/get-one-employee"},{"title":"Change an employee's personal and contact details","deprecated":null,"version":null,"openapi":"/openapi.json patch /employees/{id}","href":"/api-reference/directory/change-an-employees-personal-and-contact-details"},{"title":"List published employee events","deprecated":null,"version":null,"openapi":"/openapi.json get /events","href":"/api-reference/directory/list-published-employee-events"}]},{"group":"Organisation","pages":[{"title":"List the key's companies","deprecated":null,"version":null,"openapi":"/openapi.json get /companies","href":"/api-reference/organisation/list-the-keys-companies"},{"title":"List the structure's units below Company","deprecated":null,"version":null,"openapi":"/openapi.json get /org-units","href":"/api-reference/organisation/list-the-structures-units-below-company"},{"title":"List locations","deprecated":null,"version":null,"openapi":"/openapi.json get /locations","href":"/api-reference/organisation/list-locations"},{"title":"List a lookup's values","deprecated":null,"version":null,"openapi":"/openapi.json get /lookups/{type}","href":"/api-reference/organisation/list-a-lookups-values"}]},{"group":"Positions","pages":[{"title":"List positions","deprecated":null,"version":null,"openapi":"/openapi.json get /positions","href":"/api-reference/positions/list-positions"}]},{"group":"Time off","pages":[{"title":"List absences that were approved: approved, or cancelled once withdrawn (dates only, never the leave type)","deprecated":null,"version":null,"openapi":"/openapi.json get /time-off","href":"/api-reference/time-off/list-absences-that-were-approved:-approved-or-cancelled-once-withdrawn-dates-only-never-the-leave-type"}]},{"group":"Job history","pages":[{"title":"A person's job history, newest first","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/job-history","href":"/api-reference/job-history/a-persons-job-history-newest-first"},{"title":"List job-history entries across the key's companies","deprecated":null,"version":null,"openapi":"/openapi.json get /job-history","href":"/api-reference/job-history/list-job-history-entries-across-the-keys-companies"},{"title":"File a promotion, transfer or re-grade","deprecated":null,"version":null,"openapi":"/openapi.json post /employees/{id}/job-changes","href":"/api-reference/job-history/file-a-promotion-transfer-or-re-grade"},{"title":"Get a job change","deprecated":null,"version":null,"openapi":"/openapi.json get /job-changes/{id}","href":"/api-reference/job-history/get-a-job-change"},{"title":"Withdraw a pending job change","deprecated":null,"version":null,"openapi":"/openapi.json post /job-changes/{id}/withdraw","href":"/api-reference/job-history/withdraw-a-pending-job-change"}]},{"group":"Leave","pages":[{"title":"List the leave types","deprecated":null,"version":null,"openapi":"/openapi.json get /leave-types","href":"/api-reference/leave/list-the-leave-types"},{"title":"A person's leave balances","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/leave-balances","href":"/api-reference/leave/a-persons-leave-balances"},{"title":"List leave requests (never a sick request)","deprecated":null,"version":null,"openapi":"/openapi.json get /leave-requests","href":"/api-reference/leave/list-leave-requests-never-a-sick-request"},{"title":"Get one leave request","deprecated":null,"version":null,"openapi":"/openapi.json get /leave-requests/{id}","href":"/api-reference/leave/get-one-leave-request"},{"title":"Request leave for an employee","deprecated":null,"version":null,"openapi":"/openapi.json post /employees/{id}/leave-requests","href":"/api-reference/leave/request-leave-for-an-employee"},{"title":"Withdraw a leave request this key made","deprecated":null,"version":null,"openapi":"/openapi.json post /leave-requests/{id}/withdraw","href":"/api-reference/leave/withdraw-a-leave-request-this-key-made"}]},{"group":"Certifications","pages":[{"title":"A person's current certifications","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/certifications","href":"/api-reference/certifications/a-persons-current-certifications"}]},{"group":"Pay","pages":[{"title":"Get an employee's current pay package","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/pay","href":"/api-reference/pay/get-an-employees-current-pay-package"},{"title":"List an employee's pay packages, newest first","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/pay-history","href":"/api-reference/pay/list-an-employees-pay-packages-newest-first"},{"title":"File an increase, promotion or adjustment of pay","deprecated":null,"version":null,"openapi":"/openapi.json post /employees/{id}/pay-changes","href":"/api-reference/pay/file-an-increase-promotion-or-adjustment-of-pay"},{"title":"Get a pay change","deprecated":null,"version":null,"openapi":"/openapi.json get /pay-changes/{id}","href":"/api-reference/pay/get-a-pay-change"},{"title":"Withdraw a pending pay change","deprecated":null,"version":null,"openapi":"/openapi.json post /pay-changes/{id}/withdraw","href":"/api-reference/pay/withdraw-a-pending-pay-change"}]},{"group":"Performance","pages":[{"title":"List an employee's released final performance ratings","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/performance-ratings","href":"/api-reference/performance/list-an-employees-released-final-performance-ratings"}]},{"group":"Documents","pages":[{"title":"List an employee's documents, newest first","deprecated":null,"version":null,"openapi":"/openapi.json get /employees/{id}/documents","href":"/api-reference/documents/list-an-employees-documents-newest-first"},{"title":"Download a document","description":"Needs the Documents field group. Documents, approved by the Information Officer. Answers 302 with a signed URL in `Location`, valid for 5 minutes: follow it at once and do not store it. Every download is recorded against the key. A document the key may not list answers 404 (`not-found`), as one that does not exist. A contract's sealed copy is held by the signing provider, so its download answers 404.","deprecated":null,"version":null,"openapi":"/openapi.json get /documents/{id}/download","href":"/api-reference/documents/download-a-document"}]},{"group":"Hires","pages":[{"title":"File a new hire: a prefilled draft offer HR completes","deprecated":null,"version":null,"openapi":"/openapi.json post /hires","href":"/api-reference/hires/file-a-new-hire:-a-prefilled-draft-offer-hr-completes"},{"title":"Get one hire and its status","description":"Needs the Hires field group's Write switch. `status` is read live from the offer: `draft` until HR starts it and while it is in draft, then `awaiting_approval`, `approved` (approved, not yet sent), `sent`, and `signed` or `declined`. `withdrawn`: the offer was voided or the candidate removed. Hires of the key's companies only.","deprecated":null,"version":null,"openapi":"/openapi.json get /hires/{id}","href":"/api-reference/hires/get-one-hire-and-its-status"}]},{"group":"Authentication","pages":[{"title":"Get an access token (OAuth client credentials)","deprecated":null,"version":null,"openapi":"/openapi.json post /oauth/token","href":"/api-reference/authentication/get-an-access-token-oauth-client-credentials"}]},{"group":"Reference","pages":[{"title":"This document","deprecated":null,"version":null,"openapi":"/openapi.json get /openapi.json","href":"/api-reference/reference/this-document"}]},{"group":"Webhooks","pages":[{"title":"Employeehired","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.hired","href":"/api-reference/webhooks/employeehired"},{"title":"Employeestarted","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.started","href":"/api-reference/webhooks/employeestarted"},{"title":"Employeechanged","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.changed","href":"/api-reference/webhooks/employeechanged"},{"title":"Employeeleaving","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.leaving","href":"/api-reference/webhooks/employeeleaving"},{"title":"Employeeleft","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.left","href":"/api-reference/webhooks/employeeleft"},{"title":"Employeehire withdrawn","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.hire_withdrawn","href":"/api-reference/webhooks/employeehire_withdrawn"},{"title":"Employeetermination cancelled","version":null,"deprecated":null,"openapi":"/openapi.json webhook employee.termination_cancelled","href":"/api-reference/webhooks/employeetermination_cancelled"},{"title":"Hirestatus changed","version":null,"deprecated":null,"openapi":"/openapi.json webhook hire.status_changed","href":"/api-reference/webhooks/hirestatus_changed"},{"title":"Job changerequested","version":null,"deprecated":null,"openapi":"/openapi.json webhook job_change.requested","href":"/api-reference/webhooks/job_changerequested"},{"title":"Job changedecided","version":null,"deprecated":null,"openapi":"/openapi.json webhook job_change.decided","href":"/api-reference/webhooks/job_changedecided"},{"title":"Pay changerequested","version":null,"deprecated":null,"openapi":"/openapi.json webhook pay_change.requested","href":"/api-reference/webhooks/pay_changerequested"},{"title":"Pay changedecided","version":null,"deprecated":null,"openapi":"/openapi.json webhook pay_change.decided","href":"/api-reference/webhooks/pay_changedecided"},{"title":"Leave requestsubmitted","version":null,"deprecated":null,"openapi":"/openapi.json webhook leave_request.submitted","href":"/api-reference/webhooks/leave_requestsubmitted"},{"title":"Leave requestdecided","version":null,"deprecated":null,"openapi":"/openapi.json webhook leave_request.decided","href":"/api-reference/webhooks/leave_requestdecided"},{"title":"Performancerating released","version":null,"deprecated":null,"openapi":"/openapi.json webhook performance.rating_released","href":"/api-reference/webhooks/performancerating_released"},{"title":"Documentadded","version":null,"deprecated":null,"openapi":"/openapi.json webhook document.added","href":"/api-reference/webhooks/documentadded"}]}]},{"tab":"Changelog","pages":[{"title":"Changelog","href":"/api/changelog"}]}]},"basePath":"","title":"File a new hire: a prefilled draft offer HR completes - andteam","buildId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","deploymentId":"dpl_DqYu5MPb49gWBBbUGgpHQUmCHY3P","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CybtLBIt.js","utils-BMLj2fvV.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-B6In562Y.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-Dr8Mfhp9.js","snippetPresets-2rmQvMVl.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","conditional-requirements-CFM0id0Q.js","ApiExamples-WMqJYdZj.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-CJ-MlPHu.js","shallow-dY3TMRCk.js","getApiPlaygroundDisplay-v-1B2bKm.js","CodeSnippet-BDhiTB7U.js","CodeSnippets-D9hnzQcS.js","Page-C4GwDT3_.js","getPastedJson-Th2V45jI.js","icon-BQXch1W9.js","MethodPill-BCqUneP3.js","DuplicateIcon-Q_-bhurZ.js","createIcon-DUjLHRqp.js","DynamicMarkdown-B-f2cqXQ.js","SectionHeading-Da5NsV4v.js","axios-vUo_bRtp.js","Markdown-D13FWkIM.js","clsx-D3Isdib3.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-C-XZBk9h.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink--qIqmmVG.js"]}