Candidate Portal

Endpoints for candidates to view their application status, respond to offers, and download offer letters. Authentication is via a magic token sent to the candidate's email.

Auth: All endpoints require a token query parameter. This token is sent to the candidate via email after applying.

Get Candidate Profile

GET/api/public/candidate/me

Get candidate profile, timeline, interviews, and offer details.

Query Param	Type	Required	Description
`token`	string	Required	Magic token from email

Response (200)

{ "candidate": { "id": "...", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "stage": "screening", "job": { "title": "Software Engineer", "department": "Engineering", "location": "Remote" } }, "timeline": [ { "action": "applied", "createdAt": "2024-01-15T10:30:00Z" } ], "interviews": [ { "roundType": "technical", "scheduledAt": "2024-01-20T14:00:00Z", "interviewer": { "name": "HR User" } } ], "offer": { "offeredCTC": 120000, "designation": "Senior Engineer", "status": "sent" } }

Errors

Status	Message
`400`	Token is required
`401`	Invalid or expired link

Respond to Offer

PATCH/api/public/candidate/me/offer

Accept or reject a job offer.

Query Param	Type	Required	Description
`token`	string	Required	Magic token from email

Request Body

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

Response (200)

{ "offer": { "id": "...", "status": "accepted", "offeredCTC": 120000 } }

Errors

Status	Message
`400`	action must be 'accept' or 'reject'
`400`	Offer is not in a pending state
`404`	No offer found
`401`	Invalid or expired link

Get Offer Letter

GET/api/public/candidate/me/letter

Download the offer letter as HTML.

Query Param	Type	Required	Description
`token`	string	Required	Magic token from email

Response (200)

Returns HTML content with Content-Type: text/html

Errors

Status	Message
`404`	No offer found for this candidate
`401`	Invalid or expired link