Candidate Management Guide

This guide covers candidate assessment operations in the DeePsy API v1, including candidate listing, test management, result analysis, and report generation.

Overview

The Candidate Management API allows you to:

• List candidates for specific campaigns
• View candidate test details and progress
• Unlock tests for candidates using credits
• Retrieve detailed assessment results
• Generate PDF reports for candidates
• Send follow-up emails to candidates

Prerequisites

Before using candidate management endpoints, ensure you have:

1. API Authentication: Set up your API key following our Authentication Guide
2. Required Permissions: Usually MANAGE_CAMPAIGN, REPORT, or EMAIL depending on the operation - see our Permissions Guide for details

List Campaign Candidates

Retrieve all candidates for a specific campaign with their assessment status.

Endpoint

GET /candidates/{company_id}/{campaign_id}/list

Query Parameters

This endpoint supports the standard list query parameters:

• page (integer, default: 1): Page number
• limit (integer, default: 10, max: 100): Items per page
• order (string, default: "desc"): Sort order ("asc" or "desc")
• order_by (string, default: "created_at"): Field to sort by
• query (string): Search candidates by name or email

Example Request

cURL

curl -X GET "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/list" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

JavaScript

const response = await fetch('https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/list', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer deepsy-dev-your-api-key-here'
  }
});

const candidates = await response.json();
console.log(candidates);

TypeScript

interface Candidate {
  candidate_id: string;
  first_name: string;
  last_name: string;
  email: string;
  status: string;
  invited_at: string;
  started_at: string | null;
  completed_at: string | null;
  overall_score: number | null;
  tests_completed: number;
  tests_total: number;
  progress_percentage: number;
}

interface CandidateListResponse {
  items: Candidate[];
  count: number;
  pages: number;
}

const response = await fetch('https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/list', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer deepsy-dev-your-api-key-here'
  }
});

const candidates: CandidateListResponse = await response.json();
console.log(candidates);

PHP

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => 'https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/list',
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Bearer deepsy-dev-your-api-key-here'
  ],
]);

$response = curl_exec($curl);
$candidates = json_decode($response, true);

curl_close($curl);
print_r($candidates);
?>

Response

{
  "items": [
    {
      "candidate_id": "cand_123456789",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "status": "completed",
      "invited_at": "2023-01-01T00:00:00Z",
      "started_at": "2023-01-02T10:00:00Z",
      "completed_at": "2023-01-02T11:30:00Z",
      "overall_score": 78.5,
      "tests_completed": 3,
      "tests_total": 3,
      "progress_percentage": 100
    },
    {
      "candidate_id": "cand_987654321",
      "first_name": "Jane",
      "last_name": "Smith",
      "email": "jane.smith@example.com",
      "status": "in_progress",
      "invited_at": "2023-01-01T00:00:00Z",
      "started_at": "2023-01-03T09:00:00Z",
      "completed_at": null,
      "overall_score": null,
      "tests_completed": 1,
      "tests_total": 3,
      "progress_percentage": 33.3
    }
  ],
  "count": 2,
  "pages": 1
}

List Candidate Tests

Retrieve detailed information about all tests assigned to a specific candidate.

Endpoint

GET /candidates/{company_id}/{campaign_id}/{candidate_id}/list-tests

Example Request

curl -X GET "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/cand_123456789/list-tests" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Response

{
  "candidate": {
    "candidate_id": "cand_123456789",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "tests": [
    {
      "test_id": "test_personality",
      "name": "Personality Assessment",
      "description": "Comprehensive personality evaluation",
      "status": "completed",
      "score": 82.5,
      "started_at": "2023-01-02T10:00:00Z",
      "completed_at": "2023-01-02T10:45:00Z",
      "duration_minutes": 45,
      "is_unlocked": true,
      "attempt_ref": "attempt_abc123"
    },
    {
      "test_id": "test_cognitive",
      "name": "Cognitive Ability Test",
      "description": "Cognitive skills assessment",
      "status": "completed",
      "score": 75.0,
      "started_at": "2023-01-02T11:00:00Z",
      "completed_at": "2023-01-02T11:30:00Z",
      "duration_minutes": 30,
      "is_unlocked": true,
      "attempt_ref": "attempt_def456"
    }
  ],
  "overall_progress": {
    "completed_tests": 2,
    "total_tests": 3,
    "percentage": 66.7,
    "overall_score": 78.75
  }
}

Unlock Test for Candidate

Unlock a specific test for a candidate using company credits. This allows the candidate to take the assessment.

Endpoint

POST /candidates/{company_id}/{campaign_id}/{candidate_id}/unlock-test

Required Permissions

• MANAGE_CAMPAIGN or higher

Request Body

{
  "test_id": "test_leadership",
  "send_notification": true,
  "custom_message": "Your leadership assessment is now available"
}

Example Request

curl -X POST "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/cand_123456789/unlock-test" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "test_id": "test_leadership",
    "send_notification": true
  }'

Response

{
  "success": true,
  "test_id": "test_leadership",
  "candidate_id": "cand_123456789",
  "unlocked_at": "2023-01-05T10:00:00Z",
  "credits_used": 1,
  "remaining_credits": 24,
  "notification_sent": true
}

Get Candidate Attempt Details

Retrieve detailed results and analysis for a specific test attempt.

Endpoint

GET /candidates/{company_id}/{campaign_id}/{candidate_id}/get-attempt-details

Query Parameters

• attempt_ref (required): The specific attempt reference
• include_raw_data (optional): Include raw test responses

Example Request

curl -X GET "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/cand_123456789/get-attempt-details?attempt_ref=attempt_abc123" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here"

Response

{
  "attempt_ref": "attempt_abc123",
  "test_id": "test_personality",
  "candidate": {
    "candidate_id": "cand_123456789",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "results": {
    "overall_score": 82.5,
    "percentile": 78,
    "started_at": "2023-01-02T10:00:00Z",
    "completed_at": "2023-01-02T10:45:00Z",
    "duration_minutes": 45,
    "dimensions": [
      {
        "name": "Extraversion",
        "score": 75,
        "percentile": 68,
        "description": "Moderate to high extraversion"
      },
      {
        "name": "Conscientiousness",
        "score": 90,
        "percentile": 85,
        "description": "Very high conscientiousness"
      }
    ]
  },
  "interpretation": {
    "summary": "Strong performance with high conscientiousness and moderate extraversion",
    "strengths": ["Detail-oriented", "Reliable", "Goal-focused"],
    "development_areas": ["Team collaboration", "Public speaking"]
  }
}

Send Follow-up Email

Send a personalized follow-up email to a candidate.

Endpoint

POST /candidates/{company_id}/{campaign_id}/{candidate_id}/followup-email

Required Permissions

• EMAIL permission

Request Body

{
  "subject": "Thank you for completing the assessment",
  "message": "Thank you for taking the time to complete our assessment. We will be in touch soon with next steps.",
  "include_results_summary": false
}

Example Request

curl -X POST "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/cand_123456789/followup-email" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "subject": "Assessment Complete - Next Steps",
    "message": "Thank you for completing our assessment."
  }'

Generate PDF Report

Generate a comprehensive PDF report for a candidate's assessment results.

Single Attempt Report

POST /candidates/{company_id}/{campaign_id}/{candidate_id}/{attempt_ref}/generate-pdf

Bulk Report Generation

POST /candidates/{company_id}/{campaign_id}/{candidate_id}/bulk-generate-pdf

Example Request (Single Report)

curl -X POST "https://deepsy.fr/api/v1/candidates/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/cand_123456789/attempt_abc123/generate-pdf" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "include_detailed_analysis": true,
    "include_recommendations": true,
    "template": "comprehensive"
  }'

Response

{
  "report_id": "report_123456789",
  "pdf_url": "https://deepsy.fr/reports/report_123456789.pdf",
  "generated_at": "2023-01-05T15:30:00Z",
  "expires_at": "2023-01-12T15:30:00Z",
  "file_size_bytes": 2048576
}

Candidate Statuses

Status	Description
invited	Candidate has been invited but hasn't started
started	Candidate has begun the assessment
in_progress	Candidate is actively taking tests
completed	All tests completed successfully
incomplete	Assessment started but not finished
expired	Invitation or assessment has expired

Interactive Candidate Progress Tracker

Use this interactive tool to track candidate progress through assessments. You can add candidates, update their status, and monitor completion rates.

Candidate Progress Tracker

Monitor candidate assessment progress and completion rates

Add New Candidate

Candidate Progress

John Doe

john.doe@example.com

Status:InvitedStartedIn ProgressCompletedIncompleteExpired

Tests Progress:/ 3(100.0%)

Invited:Jan 1, 10:00 AM

Started:Jan 2, 09:00 AM

Completed:Jan 2, 11:30 AM

Score:85.5%

Jane Smith

jane.smith@example.com

Status:InvitedStartedIn ProgressCompletedIncompleteExpired

Tests Progress:/ 3(66.7%)

Invited:Jan 1, 10:00 AM

Started:Jan 3, 02:00 PM

Summary

Total Candidates:2

Completed:1

In Progress:1

Average Score:85.5%

Best Practices

1. Credit Management: Monitor credit usage when unlocking tests
2. Progress Tracking: Regularly check candidate progress and send reminders
3. Report Generation: Generate reports promptly after completion
4. Data Privacy: Handle candidate data according to privacy regulations
5. Follow-up Communication: Maintain professional communication with candidates

Related Guides

• Campaign Management Guide - Create and manage campaigns
• Company Users Guide - Manage company users and memberships
• Permissions Guide - Understand required permissions
• Error Handling Guide - Handle API errors effectively