Skip to main content
POST
/
api
/
public
/
interview
/
invite
Interview Invite
curl --request POST \
  --url https://api.tidyhire.app/api/public/interview/invite \
  --header 'Content-Type: application/json' \
  --header 'x-tidyhire-api-key: <api-key>' \
  --data '
{
  "external_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.",
  "experience_level": "5-8 Years",
  "seniority_level": "Senior",
  "work_type": "Remote",
  "employment_type": "Full Time",
  "location": "New York, NY",
  "must_have_skills": [
    "JavaScript",
    "Node.js",
    "MongoDB"
  ],
  "good_to_have_skills": [
    "TypeScript",
    "Redis"
  ],
  "candidates": [
    {
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "+1234567890",
      "metadata": {
        "source": "linkedin",
        "ats_candidate_id": "12345"
      }
    }
  ],
  "interview_settings": {
    "cutoff_score": 65,
    "interview_duration": "30 Minutes"
  },
  "metadata": {}
}
'
{
  "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",
        "metadata": {
          "source": "linkedin"
        }
      }
    ]
  }
}
Use the same external_id across multiple requests to invite candidates to an existing job.

Authorizations

​
x-tidyhire-api-key
string
header
required

Your Tidyhire API key

Body

application/json
​
external_id
string
required

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

Minimum string length: 1
Example:

"ats-job-12345"

​
job_title
string
required

The title of the job position.

Minimum string length: 1
Example:

"Senior Software Engineer"

​
job_description
string
required

A detailed description of the job role and responsibilities.

Minimum string length: 1
Example:

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

​
experience_level
enum<string>
required

Required experience level.

Available options:
Fresher,
1-2 Years,
2-5 Years,
5-8 Years,
8-12 Years,
Above 12 Years
Example:

"5-8 Years"

​
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"

​
must_have_skills
string[]
required

List of required skills. Minimum 3 skills.

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

List of preferred skills.

Example:
["TypeScript", "Redis"]
​
candidates
object[]
required

List of candidates to invite. Minimum 1 candidate. Duplicate emails (already invited to this project) are skipped and returned in the response.

Minimum array length: 1
​
interview_settings
object
​
metadata
object

Custom key-value data to attach to the project.

Example:
{}

Response

Candidates queued successfully. Background processing (question generation, candidate creation, email sending) starts after this response.

​
success
boolean
Example:

true

​
data
object