Candidate Actions

Perform actions on candidates to move them through the interview pipeline — check their status, send interview invitations, and record hiring decisions.

Returns the candidate’s current status, whether their analysis has been viewed, and their interview score.

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

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

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "status": "interviewed",
    "analysisViewed": true,
    "interviewScore": 85
  }
}

Send an interview invitation to a candidate. This creates a 7-day interview session link, updates the candidate’s status to invited, and queues an invitation email.

The candidate must have a status of new to be invited. You can customize the email subject and body — use the {interviewLink} placeholder in emailBody to insert the generated interview URL.

Scope: action:invite | Rate limit: actions (30 requests / 60s) | Idempotent: supports Idempotency-Key header

curl -X POST https://api.celper.ai/v1/candidates/cand_xyz789/invite -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -H "Idempotency-Key: invite-cand_xyz789-2026-04-11" -d '{
  "jobPositionId": "pos_abc123",
  "emailSubject": "Your interview for Senior Developer at Acme Corp",
  "emailBody": "Hi Jonas,

We would like to invite you to complete an AI-powered interview for the Senior Developer position.

Please click the link below to begin:
{interviewLink}

The link expires in 7 days.

Best regards,
Acme Corp Hiring Team"
}'

{
  "success": true,
  "requestId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "data": {
    "invited": true,
    "sessionId": "sess_abc123",
    "emailDelivery": "pending",
    "expiresAt": "2026-04-18T08:00:00.000Z"
  }
}

Mark a candidate as selected (hired). The candidate must have interviewed status and their analysis must have been viewed (analysisViewed must be true).

Scope: action:decide | Rate limit: actions (30 requests / 60s) | Idempotent: supports Idempotency-Key header

curl -X POST https://api.celper.ai/v1/candidates/cand_xyz789/select -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -H "Idempotency-Key: select-cand_xyz789" -d '{"jobPositionId": "pos_abc123"}'

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

Mark a candidate as rejected. The candidate must have interviewed status and their analysis must have been viewed (analysisViewed must be true).

Scope: action:decide | Rate limit: actions (30 requests / 60s) | Idempotent: supports Idempotency-Key header

curl -X POST https://api.celper.ai/v1/candidates/cand_xyz789/reject -H "X-API-Key: celp_your_api_key_here" -H "Content-Type: application/json" -H "Idempotency-Key: reject-cand_xyz789" -d '{"jobPositionId": "pos_abc123"}'

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