Candidates API Overview

The Candidates API provides comprehensive access to candidate information, including personal details, assessment history, resume data, and skills analysis.

Available Endpoints

Core Candidate Operations

Endpoint	Method	Description
/candidates/	GET	Get all candidates of an organization
/candidates/{candidate_id}	GET	Get detailed candidate information
/candidates/{candidate_id}/resume	GET	Get candidate resume data and profile information
/candidates/by_email/{candidate_email}	GET	Get detailed candidate information by email

Overview of available candidate endpoints and their relationships

Key Features

Candidate Management

• Retrieve all candidates associated with your organization
• Access detailed profiles including personal information and assessment history
• View resume information with parsed properties and extracted skills
• Search by email for quick candidate lookup

Data Available

Personal Information

• Name, email, and phone number
• Contact details and basic demographics

Assessment Data

• All assessments the candidate has been invited to or completed
• Assessment status and completion information
• AI-generated scores and evaluations
• Test results and performance metrics

Resume Analysis

• Parsed resume properties (location, seniority, job title)
• Extracted skills with years of experience
• Work history and employment details
• Resume text content for detailed analysis

Common Use Cases

Talent Pipeline Management

• Get overview of all candidates in your recruitment pipeline
• Track candidate progress through different assessments
• Monitor completion rates and assessment status

Candidate Evaluation

• Access detailed candidate profiles for interview preparation
• Review assessment results and AI-generated scores
• Analyze skills and experience matching

Resume Processing

• Extract and analyze resume information automatically
• Get structured data from uploaded resumes
• Access both raw resume text and parsed properties

Reporting and Analytics

• Generate reports on candidate performance
• Analyze trends in candidate skills and experience
• Track assessment completion and success rates

Pagination and Limits

Pagination Support

• Results are paginated with a maximum of 500 candidates per page
• Use the page parameter to navigate through result pages
• Response includes pagination metadata (total, page, num_pages, page_size)

Example Pagination Response

{
  "candidates": [...],
  "total": 1250,
  "page": 1,
  "num_pages": 3,
  "page_size": 500
}

Authentication and Permissions

All candidate endpoints require:

• Valid API key for authentication
• Organization membership - candidates must be part of assessments in your organization
• Appropriate permissions to access candidate data

Access Control

• You can only access candidates who are part of assessments in your organization
• Attempting to access candidates from other organizations will result in a 403 error
• Deleted or inactive candidates may not appear in results

Authentication and permission flow for candidate endpoints

Response Formats

Standard Response Structure

All candidate endpoints return JSON responses with consistent structure:

• Personal information in standardized format
• Assessment data with status and scoring information
• Metadata including timestamps and identifiers
• Error handling with detailed error messages

Common Response Fields

• id: Unique candidate identifier
• name: Candidate's full name
• email: Primary email address
• phone: Contact phone number
• assessments: Array of assessment information
• created_at/updated_at: Timestamp information

Error Handling

Common error responses you may encounter:

Status Code	Description	Common Causes
403	Not authorized	Candidate not in your organization
404	Not found	Invalid candidate ID or email
422	Validation Error	Invalid parameters or request format
500	Internal server error	System error, contact support