Skip to main content
POST
/
api
/
v1
/
candidates
Create candidate
curl --request POST \
  --url https://app.outhire.ai/api/v1/candidates \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "job_id": 40,
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+61 412 345 678",
  "linkedin": "https://linkedin.com/in/janedoe",
  "location": "Sydney, Australia",
  "stage": "prospect",
  "notes": "Referred by internal team"
}
'
{
  "data": {
    "id": 419,
    "public_id": "e3745169-a137-4b99-8fcc-373d6d4c8d60",
    "name": "Jane Doe",
    "email": "jane@example.com",
    "phone": "+61412345678",
    "linkedin": "https://linkedin.com/in/janedoe",
    "location": "Sydney, Australia",
    "stage": "applied",
    "rating": 4,
    "fit_score": 82,
    "application_source": "public_api",
    "ats_candidate_id": "ext-456",
    "job": {
      "id": 40,
      "title": "Senior Engineer"
    },
    "created_at": "2026-03-11T10:21:54.289003Z",
    "updated_at": "2026-03-11T10:21:54.544000Z",
    "applied_at": "2026-03-11T10:21:54.289003Z",
    "resume_url": "https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...",
    "resume_data": {
      "personalInfo": {
        "name": "Jane Doe",
        "email": "jane@example.com"
      },
      "summary": "Senior engineer with 8 years of experience"
    },
    "resume_status": "processed"
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

Request body for creating a candidate via JSON.

​
job_id
integer
required

Numeric id of a job owned by the authenticated company.

Required range: x >= 1
Example:

40

​
name
string
required

Candidate name after trimming.

Required string length: 1 - 200
Example:

"Jane Doe"

​
email
string<email> | null

Optional candidate email. Used in duplicate detection by job.

Example:

"jane@example.com"

​
phone
string | null

Optional phone number. Normalized where possible.

Maximum string length: 100
Example:

"+61 412 345 678"

​
linkedin
string<uri> | null

Optional LinkedIn profile URL.

Example:

"https://linkedin.com/in/janedoe"

​
location
string | null

Optional freeform location string.

Maximum string length: 500
Example:

"Sydney, Australia"

​
stage
enum<string>

Optional initial stage. Defaults to prospect.

Available options:
prospect,
applied,
phonescreen,
inprogress,
hired,
rejected
Example:

"prospect"

​
notes
string | null

Optional note that creates a note_added activity row.

Maximum string length: 2000
Example:

"Referred by internal team"

Response

Candidate created

Wrapper for a single candidate resource.

​
data
object
required

Public representation of a candidate.

Example:
{
  "id": 419,
  "public_id": "e3745169-a137-4b99-8fcc-373d6d4c8d60",
  "name": "Jane Doe",
  "email": "jane@example.com",
  "phone": "+61412345678",
  "linkedin": "https://linkedin.com/in/janedoe",
  "location": "Sydney, Australia",
  "stage": "applied",
  "rating": 4,
  "fit_score": 82,
  "application_source": "public_api",
  "ats_candidate_id": "ext-456",
  "job": { "id": 40, "title": "Senior Engineer" },
  "created_at": "2026-03-11T10:21:54.289003Z",
  "updated_at": "2026-03-11T10:21:54.544000Z",
  "applied_at": "2026-03-11T10:21:54.289003Z",
  "resume_url": "https://api.outhire.ai/storage/cv/example.pdf?token=eyJhbGciOiJIUzI1NiIs...",
  "resume_data": {
    "personalInfo": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "summary": "Senior engineer with 8 years of experience"
  },
  "resume_status": "processed"
}