Skip to main content
POST
File a new hire: a prefilled draft offer HR completes

Authorizations

Authorization
string
header
required

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.

Headers

Idempotency-Key
string
required

Unique per request; reuse it only to retry the same request with the same body. Remembered 24 hours.

Maximum string length: 255

Query Parameters

validate_only
boolean

true: answer 200 with what would happen (the approval steps and who they resolve to, the knock-ons), and write nothing.

Body

application/json
companyId
string
required

One of the key's companies.

Required string length: 1 - 80
candidate
object
required
startDate
string<date>
required

The start date the candidate was offered, company 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])))$
position
object
required

Exactly one of positionId or new.

externalRef
object
required

Your reference. The same reference again is 409 duplicate-hire.

hiringManagerId
string

The hiring manager's employee id. Prefilled as the manager the job reports to.

Required string length: 1 - 80
pay
object

The package the candidate was offered. HR reviews it in the offer, where the tenant's pay rules apply.

requestedBy
string

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.

wouldCreate
boolean
required
duplicate
object | null
required