Candidates

Submit Job Application

POST /candidates/jobs/{jobId}/apply

Public endpoint for candidates to apply for a job opening.

Path Parameters

jobId

integer

required

Job ID to apply for

Request Body

firstName

string

required

Candidate’s first name (1-100 characters)

lastName

string

required

Candidate’s last name (1-100 characters)

string

required

Valid email address (max 255 characters)

phone

string

Phone number (max 50 characters)

resumeUrl

string

Valid URL to uploaded resume (max 1000 characters)

customAnswers

array

Array of answers to custom application questions

Show customAnswer properties

questionId

integer

required

Custom question ID

answerText

string

Text answer for open-ended questions

optionIds

array

Array of selected option IDs for multiple choice questions

Response

data

object

Created candidate application object

Example Request

curl -X POST http://localhost:8080/api/candidates/jobs/1/apply \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1 555 123 4567",
    "resumeUrl": "https://r2.openats.com/resumes/john_doe.pdf",
    "customAnswers": [
      {
        "questionId": 1,
        "answerText": "I have 5 years of experience with Node.js"
      },
      {
        "questionId": 2,
        "optionIds": [3, 5, 7]
      }
    ]
  }'

Error Codes

400

error

Invalid job ID OR Validation failed

404

error

Job not found

500

error

Failed to submit application

List Candidates for Job

GET /candidates/jobs/{jobId}

Retrieve all candidates who applied for a specific job, with optional filtering.

Path Parameters

jobId

integer

required

Job ID

Query Parameters

stageId

integer

Filter by specific pipeline stage

string

Search by candidate name or email

Response

data

array

Array of candidate objects

Show candidate properties

integer

Candidate identifier

firstName

string

First name

lastName

string

Last name

string

Email address

phone

string

Phone number

resumeUrl

string

Resume URL

currentStageId

integer

Current pipeline stage ID

Example Request

# Get all candidates for a job
curl -X GET http://localhost:8080/api/candidates/jobs/1

# Filter by stage
curl -X GET "http://localhost:8080/api/candidates/jobs/1?stageId=3"

# Search by name or email
curl -X GET "http://localhost:8080/api/candidates/jobs/1?search=john"

Error Codes

400

error

Invalid job ID

500

error

Failed to fetch candidates

Get Candidate Profile

GET /candidates/{id}

Retrieve detailed information for a specific candidate including application history.

Path Parameters

integer

required

Candidate ID

Response

data

object

Full candidate profile object including:

Show properties

integer

Candidate identifier

firstName

string

First name

lastName

string

Last name

string

Email address

phone

string

Phone number

resumeUrl

string

Resume URL

jobId

integer

Applied job ID

currentStageId

integer

Current pipeline stage

customAnswers

array

Answers to custom questions

Example Request

curl -X GET http://localhost:8080/api/candidates/1

Error Codes

400

error

Invalid candidate ID

404

error

Candidate not found

500

error

Failed to fetch candidate

Move Candidate to Stage

PUT /candidates/{id}/stage

Advance or move a candidate to a different pipeline stage. Moving to an “assessment” stage may trigger an automatic invite. Moving to an “offer” stage may generate a draft offer.

Path Parameters

integer

required

Candidate ID

Request Body

newStageId

integer

required

Target pipeline stage ID

movedBy

integer

User ID of the recruiter performing the move (defaults to 1)

Response

data

object

Updated candidate object with new stage

Example Request

curl -X PUT http://localhost:8080/api/candidates/1/stage \
  -H "Content-Type: application/json" \
  -d '{
    "newStageId": 5,
    "movedBy": 2
  }'

Error Codes

400

error

Invalid candidate ID OR Validation failed OR Stage move error

500

error

Failed to move candidate

Delete Candidate

DELETE /candidates/{id}

Permanently delete a candidate from the system.

Path Parameters

integer

required

Candidate ID to delete

Response

data

object

Deleted candidate object

Example Request

curl -X DELETE http://localhost:8080/api/candidates/1

Error Codes

400

error

Invalid candidate ID

404

error

Candidate not found

500

error

Failed to delete candidate

Getting Started

Core Endpoints

Recruitment Features

Communication

Utilities

Submit Job Application

Path Parameters

Request Body

Response

Example Request

Error Codes

List Candidates for Job

Path Parameters

Query Parameters

Response

Example Request

Error Codes

Get Candidate Profile

Path Parameters

Response

Example Request

Error Codes

Move Candidate to Stage

Path Parameters

Request Body

Response

Example Request

Error Codes

Delete Candidate

Path Parameters

Response

Example Request

Error Codes

Build docs developers (and LLMs) love

Getting Started

Core Endpoints

Recruitment Features

Communication

Utilities

Documentation Index

​Submit Job Application

​Path Parameters

​Request Body

​Response

​Example Request

​Error Codes

​List Candidates for Job

​Path Parameters

​Query Parameters

​Response

​Example Request

​Error Codes

​Get Candidate Profile

​Path Parameters

​Response

​Example Request

​Error Codes

​Move Candidate to Stage

​Path Parameters

​Request Body

​Response

​Example Request

​Error Codes

​Delete Candidate

​Path Parameters

​Response

​Example Request

​Error Codes

Build docs developers (and LLMs) love

Submit Job Application

Path Parameters

Request Body

Response

Example Request

Error Codes

List Candidates for Job

Path Parameters

Query Parameters

Response

Example Request

Error Codes

Get Candidate Profile

Path Parameters

Response

Example Request

Error Codes

Move Candidate to Stage

Path Parameters

Request Body

Response

Example Request

Error Codes

Delete Candidate

Path Parameters

Response

Example Request

Error Codes