Candidate Details

Retrieve full candidate profiles, update their information, or remove them from a job position.

GET/v1/candidates/{candidateId}

Returns the full candidate profile including all fields, scores, and analysis metadata.

Scope: read:candidates | Rate limit: reads (40 requests / 60s)

Path Parameters

Parameter	Type	Required	Description
`candidateId`	`string`	Required	The unique identifier of the candidate.

Query Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position the candidate belongs to.

curl "https://api.celper.ai/v1/candidates/cand_xyz789?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here"

200Success

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "cand_xyz789",
    "firstName": "Jonas",
    "lastName": "Kazlauskas",
    "email": "jonas@example.com",
    "phone": "+37060012345",
    "status": "interviewed",
    "cvScore": 78,
    "interviewScore": 85,
    "notes": "Strong candidate referred by engineering team",
    "cvText": "Senior developer with 5 years of experience in TypeScript...",
    "aiEvaluation": "The candidate demonstrates strong technical proficiency...",
    "upsides": [
      "Extensive TypeScript and React experience",
      "Strong communication skills demonstrated in interview"
    ],
    "shortcomings": [
      "Limited experience with infrastructure and DevOps"
    ],
    "analysisViewed": false,
    "importSource": "api",
    "importedWithoutCv": false,
    "originalCvFileName": "jonas_cv.pdf",
    "sessionId": "sess_abc123",
    "createdAt": "2026-04-01T10:00:00.000Z",
    "updatedAt": "2026-04-05T14:30:00.000Z"
  }
}

404Not found

PATCH/v1/candidates/{candidateId}

Update a candidate’s basic information. Only the fields you include in the request body will be changed.

Email uniqueness is enforced — if you change the email, it must not already belong to another candidate in the same job position. Name changes trigger a regeneration of internal search keywords.

Scope: write:candidates | Rate limit: writes (20 requests / 60s)

Path Parameters

Parameter	Type	Required	Description
`candidateId`	`string`	Required	The unique identifier of the candidate.

Query Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position the candidate belongs to.

Body Parameters

Parameter	Type	Required	Description
`firstName`	`string`	Optional	Updated first name. 1-100 characters.
`lastName`	`string`	Optional	Updated last name. 1-100 characters.
`email`	`string`	Optional	Updated email address. Must be unique within the job position.
`phone`	`string`	Optional	Updated phone number. Max 50 characters.
`notes`	`string`	Optional	Updated internal notes. Max 10 KB.

curl -X PATCH "https://api.celper.ai/v1/candidates/cand_xyz789?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -d '{
  "phone": "+37060099999",
  "notes": "Updated contact number per recruiter request"
}'

200Success

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "id": "cand_xyz789",
    "firstName": "Jonas",
    "lastName": "Kazlauskas",
    "email": "jonas@example.com",
    "phone": "+37060099999",
    "status": "interviewed",
    "notes": "Updated contact number per recruiter request",
    "updatedAt": "2026-04-11T08:15:00.000Z"
  }
}

409Duplicate candidate

400Validation error

DELETE/v1/candidates/{candidateId}

Remove a candidate from a job position. This permanently deletes all associated data including CV analysis, interview recordings, and scores.

Candidates with invited status and an active interview session cannot be deleted unless you pass force=true, which cancels the active session before deletion.

Scope: write:candidates | Rate limit: writes (20 requests / 60s)

Path Parameters

Parameter	Type	Required	Description
`candidateId`	`string`	Required	The unique identifier of the candidate.

Query Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position the candidate belongs to.
`force`	`string`	Optional	Set to `"true"` to force-delete candidates with active sessions.

curl -X DELETE "https://api.celper.ai/v1/candidates/cand_xyz789?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here"

200Success

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "deleted": true
  }
}

409Active session conflict

404Not found