Candidates

Import candidates into job positions, either one at a time or in bulk. Candidates can include CV text for automatic AI analysis.

GET/v1/candidates

Returns a paginated list of candidates for a given job position.

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

Query Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position to list candidates for.
`status`	`string`	Optional	Filter by candidate status. Valid values: `new`, `invited`, `interviewed`, `selected`, `rejected`, `expired`, `failed`, `unevaluable`.
`importSource`	`string`	Optional	Filter by import source. Valid values: `api`, `csv`, `manual`, `cv_upload`, `email`.
`limit`	`number`	Optional	Number of results to return. Min 1, max 200. Default: 50.
`cursor`	`string`	Optional	Pagination cursor from a previous response.

curl "https://api.celper.ai/v1/candidates?jobPositionId=pos_abc123&limit=20" -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,
      "analysisViewed": false,
      "importSource": "api",
      "createdAt": "2026-04-01T10:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "eyJjcmVhdGVkQXQiOiIyMDI2LTA0LTAxIn0",
    "hasMore": false
  }
}

400Missing required parameter

POST/v1/candidates

Import a single candidate into a job position. If cvText is provided and skipAnalysis is false, the CV is analyzed automatically by the AI engine. A cv_analysis_complete webhook event fires when analysis finishes.

Scope: write:candidates | Rate limit: writes (20 requests / 60s) | Idempotent: supports Idempotency-Key header

Body Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position to import the candidate into.
`firstName`	`string`	Required	Candidate first name. 1-100 characters.
`lastName`	`string`	Required	Candidate last name. 1-100 characters.
`email`	`string`	Required	Candidate email address. Must be unique within the job position.
`phone`	`string`	Optional	Candidate phone number. Max 50 characters.
`cvText`	`string`	Optional	Plain-text CV content for AI analysis. Max 100 KB.
`notes`	`string`	Optional	Internal notes about the candidate. Max 10 KB.
`skipAnalysis`	`boolean`	Optional	Skip automatic CV analysis. Default: `false`.

curl -X POST https://api.celper.ai/v1/candidates -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -H "Idempotency-Key: import-jonas-2026-04-11" -d '{
  "jobPositionId": "pos_abc123",
  "firstName": "Jonas",
  "lastName": "Kazlauskas",
  "email": "jonas@example.com",
  "phone": "+37060012345",
  "cvText": "Senior developer with 5 years of experience in TypeScript..."
}'

201Created

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "candidateId": "cand_xyz789",
    "status": "new",
    "cvScore": null,
    "firstName": "Jonas",
    "lastName": "Kazlauskas",
    "email": "jonas@example.com"
  }
}

When CV analysis completes (if cvText was provided), the response includes aiEvaluation:

201Created with CV analysis

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "candidateId": "cand_xyz789",
    "status": "new",
    "cvScore": 78,
    "firstName": "Jonas",
    "lastName": "Kazlauskas",
    "email": "jonas@example.com",
    "aiEvaluation": "Strong technical background with relevant experience in TypeScript and cloud technologies..."
  }
}

409Duplicate candidate

400Validation error

POST/v1/candidates/bulk

Import multiple candidates in a single request. Supports up to 500 candidates per batch.

When skipAnalysis is true and the batch contains 50 or fewer candidates, the import runs synchronously and returns full results. Otherwise, it runs asynchronously and returns a bulkImportId for tracking. A bulk_import_complete webhook event fires when async imports finish.

Scope: write:candidates | Rate limit: bulk_import (3 requests / 60s)

Body Parameters

Parameter	Type	Required	Description
`jobPositionId`	`string`	Required	The job position to import candidates into.
`candidates`	`array`	Required	Array of candidate objects (1-500 items). Each must include `firstName`, `lastName`, `email`. Optional: `phone`, `cvText`.
`skipAnalysis`	`boolean`	Optional	Skip automatic CV analysis for all candidates. Default: `false`.

curl -X POST https://api.celper.ai/v1/candidates/bulk -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -d '{
  "jobPositionId": "pos_abc123",
  "candidates": [
    {
      "firstName": "Jonas",
      "lastName": "Kazlauskas",
      "email": "jonas@example.com",
      "cvText": "Senior developer with 5 years of experience..."
    },
    {
      "firstName": "Laura",
      "lastName": "Petrauskiene",
      "email": "laura@example.com",
      "phone": "+37060067890"
    }
  ],
  "skipAnalysis": false
}'

200Synchronous result (skipAnalysis + 50 or fewer candidates)

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "imported": 2,
    "skipped": 0,
    "failed": 0,
    "results": [
      {
        "candidateId": "cand_xyz789",
        "email": "jonas@example.com",
        "status": "imported"
      },
      {
        "candidateId": "cand_abc012",
        "email": "laura@example.com",
        "status": "imported"
      }
    ]
  }
}

202Asynchronous processing

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "bulkImportId": "bulk_imp_abc123",
    "status": "processing",
    "totalCandidates": 2,
    "message": "Import started. You will receive a bulk_import_complete webhook when processing finishes."
  }
}

400Validation error

429Rate limited