Candidate Analysis

Access the AI-generated analysis for candidates, including CV scores, detailed evaluations, interview analysis, and original CV documents.

GET/v1/candidates/{candidateId}/cv-score

Returns the candidate’s CV score as a number between 0 and 100, or null if no CV has been analyzed.

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/cv-score?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here"

200Success

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

200No CV analyzed

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

GET/v1/candidates/{candidateId}/cv-analysis

Returns the full AI-generated CV analysis including score, evaluation text, and identified strengths and weaknesses. Supports translation to Lithuanian via the language parameter — translations are cached on first request using Google Translate API.

Scope: read:candidates | Rate limit: analysis (15 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.
`language`	`string`	Optional	Response language. Valid values: `"en"`, `"lt"`. Default: `"en"`.

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

200Success

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "cvScore": 78,
    "aiEvaluation": "The candidate demonstrates strong technical proficiency with TypeScript and React, backed by 5 years of hands-on experience. Their project portfolio shows a progression from junior to senior-level responsibilities...",
    "notes": "Strong candidate referred by engineering team",
    "upsides": [
      "Extensive TypeScript and React experience",
      "Proven track record of leading technical projects",
      "Strong open-source contributions"
    ],
    "shortcomings": [
      "Limited experience with infrastructure and DevOps",
      "No formal cloud certification"
    ],
    "language": "en",
    "isTranslated": false
  }
}

200Translated response

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "cvScore": 78,
    "aiEvaluation": "Kandidatas demonstruoja stiprius techninius gebejimus...",
    "notes": "Stiprus kandidatas, rekomenduotas inzinerijos komandos",
    "upsides": [
      "Plati TypeScript ir React patirtis",
      "Irodytas techninio vadovavimo patyrimas"
    ],
    "shortcomings": [
      "Ribota infrastrukturos ir DevOps patirtis"
    ],
    "language": "lt",
    "isTranslated": true
  }
}

404No analysis available

GET/v1/candidates/{candidateId}/cv-document

Returns a short-lived signed download URL for the candidate’s original CV file. The URL expires after 15 minutes. If no CV document is stored, available will be false.

Scope: read:candidates | Rate limit: storage (10 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/cv-document?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here"

200Document available

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "available": true,
    "downloadUrl": "https://storage.googleapis.com/celper-cvs/cand_xyz789/cv.pdf?X-Goog-Signature=...",
    "fileName": "jonas_cv.pdf",
    "contentType": "application/pdf",
    "expiresAt": "2026-04-11T08:30:00.000Z"
  }
}

200No document stored

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

GET/v1/candidates/{candidateId}/interview-analysis

Returns the AI-generated post-interview analysis, including the interview score, detailed analysis text, and completion metadata. Supports translation via the language parameter and ETag-based caching via the If-None-Match header.

Calling this endpoint marks the analysis as viewed (analysisViewed becomes true), which is a precondition for the select and reject actions.

The ETag is computed as an MD5 hash of analysisCompletedAt:analysisVersion:language.

Scope: read:candidates | Rate limit: analysis (15 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.
`language`	`string`	Optional	Response language. Valid values: `"en"`, `"lt"`. Default: `"en"`.

curl "https://api.celper.ai/v1/candidates/cand_xyz789/interview-analysis?jobPositionId=pos_abc123" -H "X-API-Key: celp_your_api_key_here" -H "If-None-Match: "a1b2c3d4e5f6""

200Success

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "interviewScore": 85,
    "analysisVersion": "v2",
    "analysis": {
      "interview_summary": {
        "overall_rating": 85,
        "summary": "The candidate demonstrated excellent problem-solving abilities during the technical interview. They articulated their approach clearly and showed strong understanding of system design principles."
      }
    },
    "analysisCompletedAt": "2026-04-05T14:30:00.000Z",
    "language": "en",
    "isTranslated": false,
    "originalLanguage": "en"
  }
}

304Not modified (ETag match)

404No interview analysis