Candidates

Manage candidates, track their progress through hiring stages, and handle offers.

Get All Candidates

GET/api/recruitment/candidates

Get all candidates with optional filters.

{ "candidates": [ { "id": "...", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "phone": "+1234567890", "stage": "screening", "source": "LinkedIn", "job": { "id": "...", "title": "Software Engineer" }, "rating": 4, "resumeUrl": "..." } ] }

Create Candidate

POST/api/recruitment/candidates

Add a new candidate.

Field	Type	Required	Description
`firstName`	string	Required	First name
`lastName`	string	Optional	Last name
`email`	string	Required	Email address
`phone`	string	Optional	Phone number
`job`	string	Required	Job ID
`source`	string	Optional	Source (Referral/LinkedIn/Naukri/Indeed/Other)
`currentCompany`	string	Optional	Current company
`experienceYears`	number	Optional	Years of experience
`currentCTC`	number	Optional	Current CTC
`expectedCTC`	number	Optional	Expected CTC
`noticePeriod`	string	Optional	Notice period

{ "candidate": { "id": "...", "firstName": "John", "stage": "applied" } }

Get Candidate

GET/api/recruitment/candidates/[id]

Get a specific candidate details.

{ "candidate": { ... full candidate object } }

Update Candidate

PATCH/api/recruitment/candidates/[id]

Update candidate information.

Field	Type	Required	Description
`firstName`	string	Optional	First name
`lastName`	string	Optional	Last name
`email`	string	Optional	Email
`rating`	number	Optional	Rating (1-5)
`notes`	string	Optional	Notes

{ "candidate": { ... updated candidate } }

Delete Candidate

DELETE/api/recruitment/candidates/[id]

Delete a candidate.

{ "success": true }

Get Candidate Timeline

GET/api/recruitment/candidates/[id]/timeline

Get candidate activity timeline.

{ "timeline": [ { "action": "stage_changed", "from": "applied", "to": "screening", "actor": "HR User", "timestamp": "2024-01-15T10:30:00Z" } ] }

Update Candidate Stage

PATCH/api/recruitment/candidates/[id]/stage

Move candidate to a different stage.

Field	Type	Required	Description
`stage`	string	Required	New stage

{ "candidate": { ... updated candidate } }

Request Stage Change

POST/api/recruitment/candidates/[id]/stage-change-request

Request approval to change candidate stage.

Field	Type	Required	Description
`requestedStage`	string	Required	Target stage
`feedback`	string	Optional	Feedback for the change

{ "success": true }

Upload Resume

POST/api/recruitment/candidates/[id]/resume

Upload or update candidate resume.

Field	Type	Required	Description
`resumeUrl`	string	Required	URL of uploaded resume

{ "candidate": { ... updated candidate } }

Convert to Employee

POST/api/recruitment/candidates/[id]/convert

Convert candidate to company employee.

Field	Type	Required	Description
`companyId`	string	Required	Company ID to add to

{ "success": true }

Get Candidate Offer

GET/api/recruitment/candidates/[id]/offer

Get offer for a specific candidate.

{ "offer": { "id": "...", "offeredCTC": 120000, "designation": "Senior Engineer", "status": "sent" } }

Create Candidate Offer

POST/api/recruitment/candidates/[id]/offer

Create an offer for a candidate.

Field	Type	Required	Description
`offeredCTC`	number	Required	Offered CTC
`designation`	string	Required	Job designation
`joiningDate`	string	Optional	Expected joining date
`department`	string	Optional	Department
`officeLocation`	string	Optional	Office location
`perks`	string	Optional	Perks description

{ "offer": { "id": "...", "status": "draft" } }

Get Candidate Interviews

GET/api/recruitment/candidates/[id]/interviews

Get all interviews for a candidate.

{ "interviews": [ { "id": "...", "roundType": "technical", "scheduledAt": "2024-01-20T14:00:00Z", "status": "scheduled" } ] }

Schedule Interview

POST/api/recruitment/candidates/[id]/interviews

Schedule an interview for a candidate.

Field	Type	Required	Description
`interviewer`	string	Required	Interviewer user ID
`roundType`	string	Required	Round type (screening/technical/manager/hr)
`scheduledAt`	string	Required	Scheduled date/time (ISO)
`meetingLink`	string	Optional	Online meeting link

{ "interview": { "id": "...", "status": "scheduled" } }

Assign Interviewer

POST/api/recruitment/candidates/[id]/assign-interviewer

Assign an interviewer to a candidate.

Field	Type	Required	Description
`role`	string	Required	Interviewer role
`user`	string	Required	User ID of interviewer
`roundType`	string	Optional	Round type

{ "candidate": { ... updated candidate } }

Remove Interviewer

DELETE/api/recruitment/candidates/[id]/assign-interviewer

Remove an interviewer from a candidate.

Field	Type	Required	Description
`index`	number	Required	Index of interviewer to remove

{ "candidate": { ... updated candidate } }

Public: Apply for Job

POST/api/public/jobs/[id]/apply

Apply for a job (public, no auth required).

Field	Type	Required	Description
`firstName`	string	Required	First name
`lastName`	string	Optional	Last name
`email`	string	Required	Email
`phone`	string	Optional	Phone

{ "candidate": { "id": "...", "stage": "applied" } }

Public: Get Candidate Profile

GET/api/public/candidate/me

Get current candidate's profile (magic token auth).

{ "candidate": { ... candidate profile } }

Public: Respond to Offer

PATCH/api/public/candidate/me/offer

Accept or reject an offer (candidate portal).

Field	Type	Required	Description
`action`	string	Required	Action (accept/reject)

{ "offer": { ... updated offer } }

Public: Get Offer Letter

GET/api/public/candidate/me/letter

Get offer letter HTML (candidate portal).

{ "letterHtml": "<html>...offer letter...</html>" }

Candidates

Manage candidates, track their progress through hiring stages, and handle offers.

Get All Candidates

GET/api/recruitment/candidates

Get all candidates with optional filters.

Create Candidate

POST/api/recruitment/candidates

Add a new candidate.

Field	Type	Required	Description
`firstName`	string	Required	First name
`lastName`	string	Optional	Last name
`email`	string	Required	Email address
`phone`	string	Optional	Phone number
`job`	string	Required	Job ID
`source`	string	Optional	Source (Referral/LinkedIn/Naukri/Indeed/Other)
`currentCompany`	string	Optional	Current company
`experienceYears`	number	Optional	Years of experience
`currentCTC`	number	Optional	Current CTC
`expectedCTC`	number	Optional	Expected CTC
`noticePeriod`	string	Optional	Notice period

{ "candidate": { "id": "...", "firstName": "John", "stage": "applied" } }

Get Candidate

GET/api/recruitment/candidates/[id]

Get a specific candidate details.

{ "candidate": { ... full candidate object } }

Update Candidate

PATCH/api/recruitment/candidates/[id]

Update candidate information.

Field	Type	Required	Description
`firstName`	string	Optional	First name
`lastName`	string	Optional	Last name
`email`	string	Optional	Email
`rating`	number	Optional	Rating (1-5)
`notes`	string	Optional	Notes

{ "candidate": { ... updated candidate } }

Delete Candidate

DELETE/api/recruitment/candidates/[id]

Delete a candidate.

{ "success": true }

Get Candidate Timeline

GET/api/recruitment/candidates/[id]/timeline

Get candidate activity timeline.

{ "timeline": [ { "action": "stage_changed", "from": "applied", "to": "screening", "actor": "HR User", "timestamp": "2024-01-15T10:30:00Z" } ] }

Update Candidate Stage

PATCH/api/recruitment/candidates/[id]/stage

Move candidate to a different stage.

Field	Type	Required	Description
`stage`	string	Required	New stage

{ "candidate": { ... updated candidate } }

Request Stage Change

POST/api/recruitment/candidates/[id]/stage-change-request

Request approval to change candidate stage.

Field	Type	Required	Description
`requestedStage`	string	Required	Target stage
`feedback`	string	Optional	Feedback for the change

{ "success": true }

Upload Resume

POST/api/recruitment/candidates/[id]/resume

Upload or update candidate resume.

Field	Type	Required	Description
`resumeUrl`	string	Required	URL of uploaded resume

{ "candidate": { ... updated candidate } }

Convert to Employee

POST/api/recruitment/candidates/[id]/convert

Convert candidate to company employee.

Field	Type	Required	Description
`companyId`	string	Required	Company ID to add to

{ "success": true }

Get Candidate Offer

GET/api/recruitment/candidates/[id]/offer

Get offer for a specific candidate.

{ "offer": { "id": "...", "offeredCTC": 120000, "designation": "Senior Engineer", "status": "sent" } }

Create Candidate Offer

POST/api/recruitment/candidates/[id]/offer

Create an offer for a candidate.

Field	Type	Required	Description
`offeredCTC`	number	Required	Offered CTC
`designation`	string	Required	Job designation
`joiningDate`	string	Optional	Expected joining date
`department`	string	Optional	Department
`officeLocation`	string	Optional	Office location
`perks`	string	Optional	Perks description

{ "offer": { "id": "...", "status": "draft" } }

Get Candidate Interviews

GET/api/recruitment/candidates/[id]/interviews

Get all interviews for a candidate.

{ "interviews": [ { "id": "...", "roundType": "technical", "scheduledAt": "2024-01-20T14:00:00Z", "status": "scheduled" } ] }

Schedule Interview

POST/api/recruitment/candidates/[id]/interviews

Schedule an interview for a candidate.

Field	Type	Required	Description
`interviewer`	string	Required	Interviewer user ID
`roundType`	string	Required	Round type (screening/technical/manager/hr)
`scheduledAt`	string	Required	Scheduled date/time (ISO)
`meetingLink`	string	Optional	Online meeting link

{ "interview": { "id": "...", "status": "scheduled" } }

Assign Interviewer

POST/api/recruitment/candidates/[id]/assign-interviewer

Assign an interviewer to a candidate.

Field	Type	Required	Description
`role`	string	Required	Interviewer role
`user`	string	Required	User ID of interviewer
`roundType`	string	Optional	Round type

{ "candidate": { ... updated candidate } }

Remove Interviewer

DELETE/api/recruitment/candidates/[id]/assign-interviewer

Remove an interviewer from a candidate.

Field	Type	Required	Description
`index`	number	Required	Index of interviewer to remove

{ "candidate": { ... updated candidate } }

Public: Apply for Job

POST/api/public/jobs/[id]/apply

Apply for a job (public, no auth required).

Field	Type	Required	Description
`firstName`	string	Required	First name
`lastName`	string	Optional	Last name
`email`	string	Required	Email
`phone`	string	Optional	Phone

{ "candidate": { "id": "...", "stage": "applied" } }

Public: Get Candidate Profile

GET/api/public/candidate/me

Get current candidate's profile (magic token auth).

{ "candidate": { ... candidate profile } }

Public: Respond to Offer

PATCH/api/public/candidate/me/offer

Accept or reject an offer (candidate portal).

Field	Type	Required	Description
`action`	string	Required	Action (accept/reject)

{ "offer": { ... updated offer } }

Public: Get Offer Letter

GET/api/public/candidate/me/letter

Get offer letter HTML (candidate portal).

{ "letterHtml": "<html>...offer letter...</html>" }

Candidates

Get All Candidates

Create Candidate

Get Candidate

Update Candidate

Delete Candidate

Get Candidate Timeline

Update Candidate Stage

Request Stage Change

Upload Resume

Convert to Employee

Get Candidate Offer

Create Candidate Offer

Get Candidate Interviews

Schedule Interview

Assign Interviewer

Remove Interviewer

Public: Apply for Job

Public: Get Candidate Profile

Public: Respond to Offer

Public: Get Offer Letter

Loading FlowZen

Candidates

Get All Candidates

Create Candidate

Get Candidate

Update Candidate

Delete Candidate

Get Candidate Timeline

Update Candidate Stage

Request Stage Change

Upload Resume

Convert to Employee

Get Candidate Offer

Create Candidate Offer

Get Candidate Interviews

Schedule Interview

Assign Interviewer

Remove Interviewer

Public: Apply for Job

Public: Get Candidate Profile

Public: Respond to Offer

Public: Get Offer Letter