Skip to main content
POST
/
api
/
public
/
v1
/
interview
/
invite
Interview Invite
curl --request POST \
  --url https://api.tidyhire.app/api/public/v1/interview/invite \
  --header 'Content-Type: application/json' \
  --header 'x-tidyhire-api-key: <api-key>' \
  --data '
{
  "ats_job_id": "ats-job-12345",
  "job_title": "Senior Software Engineer",
  "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
  "min_experience": 3,
  "max_experience": 5,
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "skills_required": [
    "JavaScript",
    "Node.js",
    "MongoDB"
  ],
  "skills_good_to_have": [
    "TypeScript",
    "Redis",
    "Docker"
  ],
  "candidates": [
    {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }
  ],
  "interview_questions": [
    {
      "id": "a1b2c3d4e5f60123456789abcdef0123",
      "question": "Tell me about a production application you led. What architecture choices did you make?",
      "type": "verbal"
    }
  ],
  "interview_settings": {
    "cutoff_score": 50,
    "interview_duration": "30 Minutes"
  }
}
'
{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "job_url": "https://jobs.tidyhire.app/company/acme/job/64a1b2c3d4e5f6a7b8c9d0e2",
    "project_login_url": "https://beta.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
    "interviews": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e3",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890"
      }
    ]
  }
}
Use the same ats_job_id across multiple requests to invite candidates to an existing job.

​
Example Request

{
  "ats_job_id": "ats-job-12345",
  "job_title": "Senior Software Engineer",
  "job_description": "We are looking for a Senior Software Engineer to join our team and build scalable backend services.",
  "min_experience": 3,
  "max_experience": 5,
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "skills_required": ["JavaScript", "Node.js", "MongoDB"],
  "skills_good_to_have": ["TypeScript", "Redis", "Docker"],
  "interview_settings": {
    "cutoff_score": 50,
    "interview_duration": "30 Minutes"
  },
  "candidates": [
    {
      "id": "ats-candidate-001",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890"
    }
  ]
}

​
Example Response

{
  "success": true,
  "data": {
    "project_id": "64a1b2c3d4e5f6a7b8c9d0e1",
    "job_url": "https://jobs.tidyhire.app/company/acme/job/64a1b2c3d4e5f6a7b8c9d0e2",
    "project_login_url": "https://beta.tidyhire.app/app/projects/64a1b2c3d4e5f6a7b8c9d0e1",
    "interviews": [
      {
        "id": "64a1b2c3d4e5f6a7b8c9d0e3",
        "name": "John Doe",
        "email": "john.doe@example.com",
        "phone": "+1234567890"
      }
    ]
  }
}

Authorizations

​
x-tidyhire-api-key
string
header
required

Your Tidyhire API key

Body

application/json
​
ats_job_id
string
required

A unique job identifier from your ATS to link this job. If a project with this ats_job_id already exists, candidates are added to it. Otherwise a new project and job are created.

Required string length: 1 - 200
Example:

"ats-job-12345"

​
job_title
string
required

The title of the job position. Hyperlinks are not allowed in this field.

Minimum string length: 1
Example:

"Senior Software Engineer"

​
job_description
string
required

A detailed description of the job role and responsibilities. Hyperlinks are not allowed in this field.

Minimum string length: 1
Example:

"We are looking for a Senior Software Engineer to join our team and build scalable backend services."

​
min_experience
number
required

Minimum years of experience required.

Example:

3

​
max_experience
number
required

Maximum years of experience required.

Example:

5

​
seniority_level
enum<string>
required

Seniority level for the role.

Available options:
Entry,
Mid,
Senior,
Lead,
Principal,
Staff
Example:

"Senior"

​
work_type
enum<string>
required

Work arrangement type.

Available options:
Remote,
On Site,
Hybrid
Example:

"Remote"

​
employment_type
enum<string>
required

Type of employment.

Available options:
Full Time,
Part Time,
Contract,
Freelance
Example:

"Full Time"

​
location
string
required

Job location.

Minimum string length: 1
Example:

"New York, NY"

​
skills_required
string[]
required

List of required skills. Minimum 3 skills.

Minimum array length: 3
Example:
["JavaScript", "Node.js", "MongoDB"]
​
skills_good_to_have
string[]
required

List of preferred skills. Minimum 3 skills.

Minimum array length: 3
Example:
["TypeScript", "Redis", "Docker"]
​
candidates
object[]
required

List of candidates to invite. Minimum 1 candidate.

Minimum array length: 1
​
interview_questions
object[]

Pre-generated interview questions. If provided, AI question generation is skipped.

​
interview_settings
object

Response

Success.

​
success
boolean
Example:

true

​
data
object
Last modified on June 11, 2026