Skip to main content
ATS is the write-heavy category - most integrations that touch it push candidates in rather than only reading them out. The write and the attachment are two calls.
Before you start
  • You have confirmed the integration supports candidate writes - see Check write support. Probe GET /api/ats/v1/candidates/create/meta.
  • You can generate a stable idempotency key per candidate.

​
Steps

1

Fetch the write schema

Build the body from this rather than hardcoding it - required fields differ per integration, and a required integration_params block means the write needs platform-specific values you must source first. See Fetch a schema.Result: The body this integration accepts.
2

Check whether the person already exists

Search before writing. Candidates are people, and the same person sourced twice becomes two records that a recruiter then has to merge by hand.
Result: Either an existing candidate to attach to, or confirmation you’re creating a new one.
3

Create the candidate

The payload nests under data. email_addresses, phone_numbers, locations, urls and tags are arrays even when you have one value.
Derive X-Idempotency-Key from your own record for this person - not a random value, not a timestamp. A retry must reuse the same key, or you create a second candidate in the customer’s ATS. See Employee for the same rule on the HRIS side.
Result: A candidate, with an id you store against your own record.
4

Attach the résumé

This is JSON, not multipart. Supply either file_url for Bindbee to fetch, or file_content inline.attachment_type is one of RESUME, COVER_LETTER, OFFER_LETTER, OTHER, or -.Result: The file attached to the candidate.
5

Read it back

A 2xx means the ATS accepted the write, not that it is visible yet.
Don’t block your UI on this - see the go-live checklist item on readback in Go-live checklist.Result: Confirmation the candidate and file landed.

​
Frequently Asked Questions

The Meta schema isn’t published for this integration. That is not the same as the write being unsupported - see Meta APIs.
The ATS enforces rules beyond the structural contract - a required field on their form, a job the candidate must be attached to, a duplicate-detection rule of their own. The detail array names the field - see Errors & issues.
A retry without a consistent X-Idempotency-Key, or no existence check before writing. Merge in the ATS - Bindbee doesn’t own the record once created - then fix the key derivation.
Confirm file_url is reachable without authentication, since Bindbee fetches it. Where it isn’t, send file_content inline instead.
Creating a candidate does not apply them to a job. Where the integration supports it, create the application separately - see Create Application.