Create Candidate

Creates a new candidate profile. Candidates can optionally be associated with a job or exist in your candidate pool without job assignments. They serve as the foundation for scheduling interviews.

Overview

The create candidate endpoint allows you to add candidates to your recruitment pipeline. Candidates can optionally be associated with one or more jobs, or exist in your candidate pool without job assignments. Job association can be added at creation time or later. Candidates can be scheduled for interviews using AI agents.

Use Cases

Application Processing: Create candidates from job applications with job association
ATS Integration: Sync candidates from external ATS systems
Manual Entry: Add candidates discovered through other channels (career fairs, referrals)
Candidate Pool: Build a candidate database without immediate job assignments
Bulk Import: Import multiple candidates for a job posting or general talent pool

Job Association (Optional)

Optional Job Assignment: Candidates can be created with or without a job association via the jobId field.

With Job: Associate candidate with a specific position at creation time
Without Job: Create candidate in your talent pool and assign to jobs later via the update endpoint
If provided, the job must exist and belong to your API key’s company

Basic Candidate Creation

With Job Association

{
  "jobId": "job-uuid",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "gdprExpiryDate": "2026-11-16"
}

Without Job Association (Candidate Pool)

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "gdprExpiryDate": "2026-11-16"
}

Comprehensive Candidate Profile

{
  "jobId": "job-uuid",
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "gdprExpiryDate": "2026-11-16",
  "metadata": {
    "source": "LinkedIn",
    "externalId": "CAND-12345",
    "notes": "Strong technical background",
    "resumeUrl": "https://storage.example.com/resumes/jane-doe.pdf",
    "linkedinUrl": "https://linkedin.com/in/janedoe"
  }
}

Note: Fields like resumeUrl and linkedinUrl are not built-in fields. You can store them in the flexible metadata object for your custom use cases.

Company Scoping

Candidates are scoped to your API key’s company. When created with a job association, the job must belong to your company. Candidates created without jobs are automatically associated with your company and can only be accessed via your company’s API keys. This ensures complete data isolation between companies.

Required Fields

Required Fields: All candidates must include:

firstName - Candidate’s first name (1-100 characters)
lastName - Candidate’s last name (1-100 characters)
gdprExpiryDate - GDPR compliance date in ISO 8601 format (must be in the future, e.g., “2026-11-16”)
At least one contact method: email OR phoneNumber (or both)

Optional Fields

jobId: UUID of job to associate candidate with (job must exist and belong to your company)
email: Valid email address (required if phoneNumber not provided)
phoneNumber: Must be in E.164 format (e.g., +1234567890) (required if email not provided)
metadata: Custom key-value pairs (max 10KB, max 5 levels deep, max 50 keys) for storing additional candidate information

Field Validation

The API enforces the following validation rules:

firstName/lastName: 1-100 characters (required)
gdprExpiryDate: Must be a valid ISO 8601 date string in the future (required)
email: Must be a valid email format (at least email or phoneNumber required)
phoneNumber: Must start with + and follow E.164 format (at least email or phoneNumber required)
jobId: Must be a valid UUID and reference an existing job in your company (optional)
metadata: Maximum size of 10KB, maximum depth of 5 levels, maximum 50 keys (optional)

Response Format

The response includes both jobId (singular) and jobIds (array) fields:

{
  "id": "candidate-uuid",
  "jobId": "job-uuid",           // First job (for backward compatibility)
  "jobIds": ["job-uuid"],        // Array of all job associations
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "[email protected]",
  "phoneNumber": "+1234567890",
  "gdprExpiryDate": "2026-11-16",
  "status": "APPLIED",
  "createdAt": "2025-11-28T10:30:00Z",
  "updatedAt": "2025-11-28T10:30:00Z"
}

Candidates Resource Guide

Learn about candidate management and workflows

Jobs Resource Guide

Understand job management

Interviews Resource Guide

Schedule interviews for candidates

API Reference

List and manage candidates

Authorizations

Authorization

string

header

required

API key for authentication using Bearer scheme

Body

application/json

firstName

string

required

Candidate's first name

Required string length: 1 - 100

Example:

"John"

lastName

string

required

Candidate's last name

Required string length: 1 - 100

Example:

"Doe"

GDPR expiry date in ISO 8601 format (must be in the future)

Example:

"2026-11-16"

string

Candidate's email address

Example:

"[email protected]"

phoneNumber

string

Candidate's phone number in E.164 format

Example:

"+421915123456"

jobId

string<uuid>

deprecated

[Deprecated - use jobIds] Optional single job ID to associate.

Example:

"123e4567-e89b-12d3-a456-426614174000"

jobIds

string<uuid>[]

Optional array of job IDs to associate the candidate with. If both jobId and jobIds are provided, jobIds takes precedence.

Required array length: 1 - 50 elements

metadata

object

Custom metadata for extensibility (key-value pairs, max 10KB, 5 levels deep, 50 keys)

Example:

{
  "source": "LinkedIn",
  "referredBy": "Jane Smith",
  "tags": ["senior", "remote-preferred"],
  "externalId": "CAND-12345"
}

Response

201 - application/json

Candidate created successfully

string

required

Candidate ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

firstName

string

required

Candidate's first name

Example:

"John"

lastName

string

required

Candidate's last name

Example:

"Doe"

status

enum<string>

required

Candidate status

Available options:

UNDEFINED,

APPLIED,

IN_PROCESS,

REJECTED,

ACCEPTED

Example:

"APPLIED"

createdAt

string<date-time>

required

Created timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

updatedAt

string<date-time>

required

Updated timestamp (UTC)

Example:

"2025-11-20T10:30:00Z"

jobId

string

deprecated

[Deprecated] Single job ID; use jobIds instead.

Example:

"987e6543-e21b-12d3-a456-426614174000"

jobIds

string<uuid>[]

Jobs the candidate is assigned to.

Maximum array length: 50

string

Candidate's email address

Example:

"[email protected]"

phoneNumber

string

Candidate's phone number

Example:

"+421915123456"

GDPR expiry date. Currently returned as a date (no time). NOTE: We plan to migrate to a timestamp with timezone (timestamptz) for global correctness.

Example:

"2026-11-16"

overallRating

number

Overall rating/match score (0-100)

Required range: 0 <= x <= 100

Example:

85

metadata

object

Custom metadata

Example:

{
  "source": "LinkedIn",
  "externalId": "CAND-12345"
}

analysisCount

number

Number of analyses for this candidate (for quick overview)

Example:

2

interviewCount

number

Number of interviews for this candidate (for quick overview)

Example:

3

links

object

Convenience links to related collections. Endpoints may be added incrementally.

Example:

{
  "analyses": "/v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/analyses",
  "interviews": "/v1/public/candidates/123e4567-e89b-12d3-a456-426614174000/interviews"
}

Overview

Agents

Jobs

Candidates

Companies

Interviews

Billing

Webhooks

Overview

Use Cases

Job Association (Optional)

Basic Candidate Creation

With Job Association

Without Job Association (Candidate Pool)

Comprehensive Candidate Profile

Company Scoping

Required Fields

Optional Fields

Field Validation

Response Format

Candidates Resource Guide

Jobs Resource Guide

Interviews Resource Guide

API Reference

Authorizations

Body

Response

Overview

Agents

Jobs

Candidates

Companies

Interviews

Billing

Webhooks

​Overview

​Use Cases

​Job Association (Optional)

​Basic Candidate Creation

​With Job Association

​Without Job Association (Candidate Pool)

​Comprehensive Candidate Profile

​Company Scoping

​Required Fields

​Optional Fields

​Field Validation

​Response Format

​Related Resources

Candidates Resource Guide

Jobs Resource Guide

Interviews Resource Guide

API Reference

Authorizations

Body

Response

Overview

Use Cases

Job Association (Optional)

Basic Candidate Creation

With Job Association

Without Job Association (Candidate Pool)

Comprehensive Candidate Profile

Company Scoping

Required Fields

Optional Fields

Field Validation

Response Format

Related Resources