Skip to main content
POST
Use the same ats_job_id across multiple requests to add more candidates to the same project.

Authorizations

string | header
required
API key of the form <token>, passed as the x-tidyhire-api-key header.

Body

Interview invitation data
string
required
Job ID from your ATS that identifies the job these candidates belong to.Example: "ats-job-12345"
string
required
Job title for the role. Also used as the project name. Hyperlinks not allowed.Example: "Senior Software Engineer"
object[]
required
Candidates to invite. Max 200 per request.
string
required
Job role and responsibilities. Hyperlinks not allowed.Example: "We are looking for a Senior Software Engineer to join our team and build scalable backend services."
number
required
Minimum years of experience required.Example: 3
number
required
Maximum years of experience required. Must be greater than min_experience.Example: 5
string
required
One of: Entry, Mid, Senior, Lead, Principal, Staff.Example: "Senior"
string
required
One of: Remote, On Site, Hybrid.Example: "Remote"
string
required
One of: Full Time, Part Time, Contract, Freelance.Example: "Full Time"
string
required
Job location.Example: "New York, NY"
string[]
required
Required skills. Minimum 3.Example: ["JavaScript", "Node.js", "MongoDB"]
string[]
required
Preferred skills. Minimum 3.Example: ["TypeScript", "Redis", "Docker"]
object[]
Your own interview questions. If not provided, we will generate the questions for you.
object
Interview configuration.

Response

Interview invitations are being processed
boolean
Indicates if the request was successful. Example: true
object

Common Errors

Reason: Every candidate failed processing — the request succeeded but no invitations were queued.