Candidate Check API

Base URL

All API paths are relative to:

https://proficient-buffalo-564.convex.site

Authentication

Use your organization API key in the Authorization header:

Authorization: Bearer <api-key>

Endpoints

Candidate check status values:

• Pending
• In Progress
• Completed
• Failed

Create candidate check

Request:

curl -X POST "https://proficient-buffalo-564.convex.site/api/v1/candidate-check" \
  -H "Authorization: Bearer <api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedinProfileLink": "https://www.linkedin.com/in/example",
    "briefingId": "<briefing-id>"
  }'

Successful response:

{
  "candidateCheckId": "<candidate-check-id>",
  "resultUrl": "/api/v1/candidate-check/<candidate-check-id>"
}

Notes:

• briefingId must belong to the same organization as the API key.
• The endpoint creates or reuses the candidate and starts an asynchronous check run.
• Use the returned resultUrl to poll status.

Get candidate check result

Request:

curl "https://proficient-buffalo-564.convex.site/api/v1/candidate-check/<candidate-check-id>" \
  -H "Authorization: Bearer <api-key>"

Behavior:

• If processing is not complete yet, response includes candidate check data with linkedinData: null.
• When completed, response includes candidate check data plus linkedinData.

Polling tip:

• Poll every 3-5 seconds until status is Completed or Failed.

Common errors

• 401 Missing or invalid Authorization header
• 403 Invalid or revoked API key
• 404 Briefing not found
• 404 Candidate check not found
• 403 Forbidden when candidate check belongs to another organization
• 400 Invalid JSON body
• 400 Missing linkedinProfileLink or briefingId
• 400 Briefing has no project
• 500 Failed to create candidate check