Candidates

Create and update candidates with the same fields as Dashboard → Candidates → Edit. POST deduplicates by email ( 201 new, 200 existing). Numbers use JSON number type; booleans use true / false.

List query parameters (GET)

GET /api/v1/candidates
Field	Type	Required	Description
search	string	No	Name or email
job_id	string (uuid)	No	Only candidates linked to this job (candidate_jobs)
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Candidate object
Field	Type	Required	Description
full_name	string	POST	Candidate full name
email	string	POST	Unique per organization
phone_number	string \| null	No	Phone number
whatsapp_number	string \| null	No	WhatsApp number
location	string \| null	No	Current location
preferred_location	string \| null	No	Preferred work location
primary_skills	string[]	No	Primary skill tags
secondary_skills	string[]	No	Secondary skill tags
total_experience_years	number \| null	No	Total experience (decimal years)
current_company	string \| null	No	Current employer
current_designation	string \| null	No	Current job title
current_ctc	number \| null	No	Current CTC in LPA
expected_ctc	number \| null	No	Expected CTC in LPA
notice_period_days	integer \| null	No	Notice period (days)
in_notice_period	boolean \| null	No	Currently serving notice
last_working_day	string (YYYY-MM-DD)	No	Last working day if in notice
resume_url	string \| null	No	Public resume URL
resume_path	string \| null	No	Internal resume storage path (create)
source	string	No	Source label (default api)
metadata	object	No	Custom JSON (e.g. ATS id)
application	object	No	Apply candidate to a job (nested fields)
application.job_id	string (uuid)	If application	Target job id
application.status	string	No	Pipeline status (must match org settings; default Applied)
application.notes	string \| null	No	Application notes

Response body

Candidate resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Candidate id
full_name	string	—	Full name
email	string	—	Email (may be empty when talent pool masked)
phone_number	string \| null	—	Phone
whatsapp_number	string \| null	—	WhatsApp
location	string \| null	—	Current location
preferred_location	string \| null	—	Preferred location
primary_skills	string[]	—	Primary skills
secondary_skills	string[]	—	Secondary skills
skill_array	string[]	—	Combined skill list
total_experience_years	number \| null	—	Experience years
current_company	string \| null	—	Current company
current_designation	string \| null	—	Current designation
current_ctc	number \| null	—	Current CTC (LPA); null if masked
expected_ctc	number \| null	—	Expected CTC (LPA); null if masked
notice_period_days	integer \| null	—	Notice period days
in_notice_period	boolean \| null	—	In notice period
last_working_day	string (YYYY-MM-DD)	—	Last working day
resume_url	string \| null	—	Resume URL (resume_text never returned)
source	string \| null	—	Candidate source
screening_score	number \| null	—	Aggregate screening score
talent_pool_status	"not_linked" \| "masked" \| "revealed"	—	Talent pool reveal state
metadata	object \| null	—	Custom metadata
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Updated timestamp

applications[] item (GET /api/v1/candidates/{id} only)
Field	Type	Required	Description
id	string (uuid)	—	candidate_jobs row id
candidate_id	string (uuid)	—	Candidate id
job_id	string (uuid)	—	Job id
organization_id	string (uuid)	—	Organization id
status	string	—	Pipeline status for this job
screening_score	number \| null	—	Screening score
match_score	number \| null	—	Match score
notes	string \| null	—	Recruiter notes
shortlisted_at	string (ISO 8601 date-time)	—	When shortlisted
screening_started_at	string (ISO 8601 date-time)	—	Screening started
screening_completed_at	string (ISO 8601 date-time)	—	Screening completed
status_date	string (ISO 8601 date-time)	—	Entered current status
outreach_sent_at	string (ISO 8601 date-time)	—	Outreach email sent
interest_clicked_at	string (ISO 8601 date-time)	—	Interest page click
video_interview_invite_sent_at	string (ISO 8601 date-time)	—	Video invite sent
metadata	object \| null	—	Application metadata
created_at	string (ISO 8601 date-time)	—	Created
updated_at	string (ISO 8601 date-time)	—	Updated

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

Talent pool: talent_pool_status may be masked; contact and CTC fields can be empty until revealed. Updating locked fields returns talent_pool_reveal_required (403).

GET/api/v1/candidates

List candidates.

GET/api/v1/candidates/{id}

Get candidate with applications[].

POST/api/v1/candidates

Create or match by email.

Example

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "phone_number": "+91 90000 12345",
  "whatsapp_number": "+91 90000 12345",
  "location": "Bangalore",
  "preferred_location": "Remote",
  "primary_skills": ["React", "TypeScript"],
  "secondary_skills": ["Docker"],
  "total_experience_years": 6,
  "current_company": "Acme Inc",
  "current_designation": "Senior Engineer",
  "current_ctc": 18,
  "expected_ctc": 24,
  "notice_period_days": 30,
  "in_notice_period": false,
  "resume_url": "https://example.com/resume.pdf",
  "metadata": { "external_id": "ATS-9912" },
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Applied",
    "notes": "Imported from ATS"
  }
}

Apply to job only (PUT)

{
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "shortlisted",
    "notes": "Strong React background"
  }
}

PUT/api/v1/candidates/{id}

Partial update.

Candidates

List query parameters (GET)

GET /api/v1/candidates
Field	Type	Required	Description
search	string	No	Name or email
job_id	string (uuid)	No	Only candidates linked to this job (candidate_jobs)
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Candidate object
Field	Type	Required	Description
full_name	string	POST	Candidate full name
email	string	POST	Unique per organization
phone_number	string \| null	No	Phone number
whatsapp_number	string \| null	No	WhatsApp number
location	string \| null	No	Current location
preferred_location	string \| null	No	Preferred work location
primary_skills	string[]	No	Primary skill tags
secondary_skills	string[]	No	Secondary skill tags
total_experience_years	number \| null	No	Total experience (decimal years)
current_company	string \| null	No	Current employer
current_designation	string \| null	No	Current job title
current_ctc	number \| null	No	Current CTC in LPA
expected_ctc	number \| null	No	Expected CTC in LPA
notice_period_days	integer \| null	No	Notice period (days)
in_notice_period	boolean \| null	No	Currently serving notice
last_working_day	string (YYYY-MM-DD)	No	Last working day if in notice
resume_url	string \| null	No	Public resume URL
resume_path	string \| null	No	Internal resume storage path (create)
source	string	No	Source label (default api)
metadata	object	No	Custom JSON (e.g. ATS id)
application	object	No	Apply candidate to a job (nested fields)
application.job_id	string (uuid)	If application	Target job id
application.status	string	No	Pipeline status (must match org settings; default Applied)
application.notes	string \| null	No	Application notes

Response body

Candidate resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Candidate id
full_name	string	—	Full name
email	string	—	Email (may be empty when talent pool masked)
phone_number	string \| null	—	Phone
whatsapp_number	string \| null	—	WhatsApp
location	string \| null	—	Current location
preferred_location	string \| null	—	Preferred location
primary_skills	string[]	—	Primary skills
secondary_skills	string[]	—	Secondary skills
skill_array	string[]	—	Combined skill list
total_experience_years	number \| null	—	Experience years
current_company	string \| null	—	Current company
current_designation	string \| null	—	Current designation
current_ctc	number \| null	—	Current CTC (LPA); null if masked
expected_ctc	number \| null	—	Expected CTC (LPA); null if masked
notice_period_days	integer \| null	—	Notice period days
in_notice_period	boolean \| null	—	In notice period
last_working_day	string (YYYY-MM-DD)	—	Last working day
resume_url	string \| null	—	Resume URL (resume_text never returned)
source	string \| null	—	Candidate source
screening_score	number \| null	—	Aggregate screening score
talent_pool_status	"not_linked" \| "masked" \| "revealed"	—	Talent pool reveal state
metadata	object \| null	—	Custom metadata
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Updated timestamp

applications[] item (GET /api/v1/candidates/{id} only)
Field	Type	Required	Description
id	string (uuid)	—	candidate_jobs row id
candidate_id	string (uuid)	—	Candidate id
job_id	string (uuid)	—	Job id
organization_id	string (uuid)	—	Organization id
status	string	—	Pipeline status for this job
screening_score	number \| null	—	Screening score
match_score	number \| null	—	Match score
notes	string \| null	—	Recruiter notes
shortlisted_at	string (ISO 8601 date-time)	—	When shortlisted
screening_started_at	string (ISO 8601 date-time)	—	Screening started
screening_completed_at	string (ISO 8601 date-time)	—	Screening completed
status_date	string (ISO 8601 date-time)	—	Entered current status
outreach_sent_at	string (ISO 8601 date-time)	—	Outreach email sent
interest_clicked_at	string (ISO 8601 date-time)	—	Interest page click
video_interview_invite_sent_at	string (ISO 8601 date-time)	—	Video invite sent
metadata	object \| null	—	Application metadata
created_at	string (ISO 8601 date-time)	—	Created
updated_at	string (ISO 8601 date-time)	—	Updated

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

Talent pool: talent_pool_status may be masked; contact and CTC fields can be empty until revealed. Updating locked fields returns talent_pool_reveal_required (403).

GET/api/v1/candidates

List candidates.

GET/api/v1/candidates/{id}

Get candidate with applications[].

POST/api/v1/candidates

Create or match by email.

Example

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "phone_number": "+91 90000 12345",
  "whatsapp_number": "+91 90000 12345",
  "location": "Bangalore",
  "preferred_location": "Remote",
  "primary_skills": ["React", "TypeScript"],
  "secondary_skills": ["Docker"],
  "total_experience_years": 6,
  "current_company": "Acme Inc",
  "current_designation": "Senior Engineer",
  "current_ctc": 18,
  "expected_ctc": 24,
  "notice_period_days": 30,
  "in_notice_period": false,
  "resume_url": "https://example.com/resume.pdf",
  "metadata": { "external_id": "ATS-9912" },
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Applied",
    "notes": "Imported from ATS"
  }
}

Apply to job only (PUT)

{
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "shortlisted",
    "notes": "Strong React background"
  }
}

PUT/api/v1/candidates/{id}

Partial update.

Candidates

List query parameters (GET)

GET /api/v1/candidates
Field	Type	Required	Description
search	string	No	Name or email
job_id	string (uuid)	No	Only candidates linked to this job (candidate_jobs)
limit	integer	No	Page size (1–100, default 50)
offset	integer	No	Skip N records (default 0)

Request body (POST / PUT)

Candidate object
Field	Type	Required	Description
full_name	string	POST	Candidate full name
email	string	POST	Unique per organization
phone_number	string \| null	No	Phone number
whatsapp_number	string \| null	No	WhatsApp number
location	string \| null	No	Current location
preferred_location	string \| null	No	Preferred work location
primary_skills	string[]	No	Primary skill tags
secondary_skills	string[]	No	Secondary skill tags
total_experience_years	number \| null	No	Total experience (decimal years)
current_company	string \| null	No	Current employer
current_designation	string \| null	No	Current job title
current_ctc	number \| null	No	Current CTC in LPA
expected_ctc	number \| null	No	Expected CTC in LPA
notice_period_days	integer \| null	No	Notice period (days)
in_notice_period	boolean \| null	No	Currently serving notice
last_working_day	string (YYYY-MM-DD)	No	Last working day if in notice
resume_url	string \| null	No	Public resume URL
resume_path	string \| null	No	Internal resume storage path (create)
source	string	No	Source label (default api)
metadata	object	No	Custom JSON (e.g. ATS id)
application	object	No	Apply candidate to a job (nested fields)
application.job_id	string (uuid)	If application	Target job id
application.status	string	No	Pipeline status (must match org settings; default Applied)
application.notes	string \| null	No	Application notes

Response body

Candidate resource (data)
Field	Type	Required	Description
id	string (uuid)	—	Candidate id
full_name	string	—	Full name
email	string	—	Email (may be empty when talent pool masked)
phone_number	string \| null	—	Phone
whatsapp_number	string \| null	—	WhatsApp
location	string \| null	—	Current location
preferred_location	string \| null	—	Preferred location
primary_skills	string[]	—	Primary skills
secondary_skills	string[]	—	Secondary skills
skill_array	string[]	—	Combined skill list
total_experience_years	number \| null	—	Experience years
current_company	string \| null	—	Current company
current_designation	string \| null	—	Current designation
current_ctc	number \| null	—	Current CTC (LPA); null if masked
expected_ctc	number \| null	—	Expected CTC (LPA); null if masked
notice_period_days	integer \| null	—	Notice period days
in_notice_period	boolean \| null	—	In notice period
last_working_day	string (YYYY-MM-DD)	—	Last working day
resume_url	string \| null	—	Resume URL (resume_text never returned)
source	string \| null	—	Candidate source
screening_score	number \| null	—	Aggregate screening score
talent_pool_status	"not_linked" \| "masked" \| "revealed"	—	Talent pool reveal state
metadata	object \| null	—	Custom metadata
created_at	string (ISO 8601 date-time)	—	Created timestamp
updated_at	string (ISO 8601 date-time)	—	Updated timestamp

applications[] item (GET /api/v1/candidates/{id} only)
Field	Type	Required	Description
id	string (uuid)	—	candidate_jobs row id
candidate_id	string (uuid)	—	Candidate id
job_id	string (uuid)	—	Job id
organization_id	string (uuid)	—	Organization id
status	string	—	Pipeline status for this job
screening_score	number \| null	—	Screening score
match_score	number \| null	—	Match score
notes	string \| null	—	Recruiter notes
shortlisted_at	string (ISO 8601 date-time)	—	When shortlisted
screening_started_at	string (ISO 8601 date-time)	—	Screening started
screening_completed_at	string (ISO 8601 date-time)	—	Screening completed
status_date	string (ISO 8601 date-time)	—	Entered current status
outreach_sent_at	string (ISO 8601 date-time)	—	Outreach email sent
interest_clicked_at	string (ISO 8601 date-time)	—	Interest page click
video_interview_invite_sent_at	string (ISO 8601 date-time)	—	Video invite sent
metadata	object \| null	—	Application metadata
created_at	string (ISO 8601 date-time)	—	Created
updated_at	string (ISO 8601 date-time)	—	Updated

List meta object
Field	Type	Required	Description
meta.total	integer	—	Total matching records
meta.limit	integer	—	Page size used
meta.offset	integer	—	Offset used

Talent pool: talent_pool_status may be masked; contact and CTC fields can be empty until revealed. Updating locked fields returns talent_pool_reveal_required (403).

GET/api/v1/candidates

List candidates.

GET/api/v1/candidates/{id}

Get candidate with applications[].

POST/api/v1/candidates

Create or match by email.

Example

{
  "full_name": "Jane Doe",
  "email": "[email protected]",
  "phone_number": "+91 90000 12345",
  "whatsapp_number": "+91 90000 12345",
  "location": "Bangalore",
  "preferred_location": "Remote",
  "primary_skills": ["React", "TypeScript"],
  "secondary_skills": ["Docker"],
  "total_experience_years": 6,
  "current_company": "Acme Inc",
  "current_designation": "Senior Engineer",
  "current_ctc": 18,
  "expected_ctc": 24,
  "notice_period_days": 30,
  "in_notice_period": false,
  "resume_url": "https://example.com/resume.pdf",
  "metadata": { "external_id": "ATS-9912" },
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "Applied",
    "notes": "Imported from ATS"
  }
}

Apply to job only (PUT)

{
  "application": {
    "job_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "shortlisted",
    "notes": "Strong React background"
  }
}

PUT/api/v1/candidates/{id}

Partial update.