Recruit API

End-to-end recruitment management — job postings, candidate tracking, applications pipeline, interviews, evaluations, and offer management.

All endpoints prefixed with /api/v1/recruit

Job Postings

Manage job openings with department and designation links.

POST /api/v1/recruit/job-postings

Create a new job posting.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "title": "Senior Developer",
  "departmentId": 1,
  "designationId": 2,
  "employmentType": "full_time",
  "location": "Remote",
  "description": "...",
  "requirements": "...",
  "salaryMin": 80000,
  "salaryMax": 120000,
  "salaryCurrency": "USD"
}
GET /api/v1/recruit/job-postings

List job postings with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
search string Search by title
status string Filter by status
departmentId number Filter by department
GET /api/v1/recruit/job-postings/stats

Get job posting statistics.

Auth: Bearer token · recruit.view

GET /api/v1/recruit/job-postings/:id

Get job posting by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/job-postings/:id

Update a job posting.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/job-postings/:id

Delete a job posting.

Auth: Bearer token · recruit.delete

POST /api/v1/recruit/job-postings/:id/publish

Publish a job posting.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/job-postings/:id/close

Close a job posting.

Auth: Bearer token · recruit.edit

Candidates

Manage candidate profiles and source tracking.

POST /api/v1/recruit/candidates

Create a new candidate.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "source": "linkedin",
  "currentCompany": "Acme Inc",
  "currentTitle": "Developer"
}
GET /api/v1/recruit/candidates

List candidates with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
search string Search by name or email
source string Filter by source
GET /api/v1/recruit/candidates/stats

Get candidate statistics.

Auth: Bearer token · recruit.view

GET /api/v1/recruit/candidates/:id

Get candidate by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/candidates/:id

Update a candidate.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/candidates/:id

Delete a candidate.

Auth: Bearer token · recruit.delete

Applications

Track candidate applications through pipeline stages.

POST /api/v1/recruit/applications

Create a new application.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "jobPostingId": 1,
  "candidateId": 1,
  "coverLetter": "..."
}
GET /api/v1/recruit/applications

List applications with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
jobPostingId number Filter by job posting
candidateId number Filter by candidate
stage string Filter by pipeline stage
GET /api/v1/recruit/applications/pipeline

Get pipeline view grouped by stage.

Auth: Bearer token · recruit.view

GET /api/v1/recruit/applications/:id

Get application by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/applications/:id

Update an application.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/applications/:id

Delete an application (cascades interviews, evaluations, offers).

Auth: Bearer token · recruit.delete

POST /api/v1/recruit/applications/:id/advance

Advance application to next pipeline stage.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/applications/:id/reject

Reject an application.

Auth: Bearer token · recruit.edit

Interviews

Schedule and manage candidate interviews.

POST /api/v1/recruit/interviews

Schedule a new interview.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "applicationId": 1,
  "interviewType": "technical",
  "scheduledAt": "2026-06-15T10:00:00Z",
  "duration": 60,
  "location": "Conference Room A",
  "interviewerIds": [1, 2]
}
GET /api/v1/recruit/interviews

List interviews with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
applicationId number Filter by application
interviewType string Filter by interview type
status string Filter by status
GET /api/v1/recruit/interviews/:id

Get interview by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/interviews/:id

Update an interview.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/interviews/:id

Delete an interview.

Auth: Bearer token · recruit.delete

POST /api/v1/recruit/interviews/:id/complete

Mark interview as completed.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/interviews/:id/cancel

Cancel an interview.

Auth: Bearer token · recruit.edit

Evaluations

Structured evaluation scorecards for interview feedback.

POST /api/v1/recruit/evaluations

Submit an evaluation.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "applicationId": 1,
  "interviewId": 1,
  "overallRating": 4,
  "technicalScore": 5,
  "communicationScore": 4,
  "cultureFitScore": 3,
  "recommendation": "strong_hire",
  "notes": "Excellent technical skills"
}
GET /api/v1/recruit/evaluations

List evaluations with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
applicationId number Filter by application
interviewId number Filter by interview
GET /api/v1/recruit/evaluations/:id

Get evaluation by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/evaluations/:id

Update an evaluation.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/evaluations/:id

Delete an evaluation.

Auth: Bearer token · recruit.delete

Offers

Manage job offers with acceptance tracking.

POST /api/v1/recruit/offers

Create a new offer.

Auth: Bearer token · recruit.create

Request Body
json 
{
  "applicationId": 1,
  "salary": 95000,
  "salaryCurrency": "USD",
  "salaryPeriod": "yearly",
  "startDate": "2026-07-01",
  "expiryDate": "2026-06-20",
  "benefits": "Health insurance, 401k"
}
GET /api/v1/recruit/offers

List offers with pagination and filtering.

Auth: Bearer token · recruit.view

Query Parameters
Parameter Type Description
page number Page number
limit number Items per page
applicationId number Filter by application
status string Filter by status
GET /api/v1/recruit/offers/:id

Get offer by ID.

Auth: Bearer token · recruit.view

PUT /api/v1/recruit/offers/:id

Update an offer.

Auth: Bearer token · recruit.edit

DELETE /api/v1/recruit/offers/:id

Delete an offer.

Auth: Bearer token · recruit.delete

POST /api/v1/recruit/offers/:id/send

Send offer to candidate.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/offers/:id/accept

Mark offer as accepted.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/offers/:id/reject

Mark offer as rejected.

Auth: Bearer token · recruit.edit

POST /api/v1/recruit/offers/:id/hire

Mark candidate as hired (triggers HR handoff).

Auth: Bearer token · recruit.manage