Campaign Management Guide

This guide covers campaign operations in the DeePsy API v1, including campaign creation, management, invitations, and asset handling.

Overview

The Campaign Management API allows you to:

• Create and manage assessment campaigns
• List and update campaign details
• Handle campaign invitations and candidate recruitment
• Manage campaign assets (images, documents, etc.)
• Bulk operations for efficiency

Prerequisites

Before using campaign management endpoints, ensure you have:

1. API Authentication: Set up your API key following our Authentication Guide
2. Required Permissions: MANAGE_CAMPAIGN permission or higher - see our Permissions Guide for details

List Campaigns

Retrieve all campaigns for a specific company.

Endpoint

GET /campaign/{company_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 campaigns by name or description

Example Request

cURL

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

JavaScript

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

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

TypeScript

interface Campaign {
  campaign_id: string;
  name: string;
  description: string;
  status: string;
  created_at: string;
  updated_at: string;
  candidates_count: number;
  invitations_sent: number;
  completion_rate: number;
}

interface CampaignListResponse {
  items: Campaign[];
  count: number;
  pages: number;
}

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

const campaigns: CampaignListResponse = await response.json();
console.log(campaigns);

PHP

<?php
$curl = curl_init();

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

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

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

Response

{
  "items": [
    {
      "campaign_id": "camp_123456789",
      "name": "Q1 2024 Recruitment Campaign",
      "description": "Psychological assessment for new hires",
      "status": "active",
      "created_at": "2023-01-01T00:00:00Z",
      "updated_at": "2023-01-15T10:30:00Z",
      "candidates_count": 25,
      "invitations_sent": 30,
      "completion_rate": 83.3
    }
  ],
  "count": 1,
  "pages": 1
}

Create Campaign

Create a new assessment campaign for your company.

Endpoint

POST /campaign/{company_id}/create

Request Body

{
  "name": "Q2 2024 Leadership Assessment",
  "description": "Comprehensive leadership evaluation for management positions",
  "settings": {
    "allow_retakes": false,
    "time_limit": 3600,
    "send_results_email": true,
    "require_consent": true
  },
  "tests": [
    "personality_assessment",
    "cognitive_ability",
    "leadership_potential"
  ]
}

Example Request

cURL

curl -X POST "https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/create" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 2024 Leadership Assessment",
    "description": "Comprehensive leadership evaluation",
    "settings": {
      "allow_retakes": false,
      "time_limit": 3600
    }
  }'

JavaScript

const campaignData = {
  name: "Q2 2024 Leadership Assessment",
  description: "Comprehensive leadership evaluation",
  settings: {
    allow_retakes: false,
    time_limit: 3600
  }
};

const response = await fetch('https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer deepsy-dev-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(campaignData)
});

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

TypeScript

interface CampaignCreateRequest {
  name: string;
  description: string;
  settings: {
    allow_retakes: boolean;
    time_limit: number;
    send_results_email?: boolean;
    require_consent?: boolean;
  };
  tests?: string[];
}

interface CampaignCreateResponse {
  campaign_id: string;
  name: string;
  description: string;
  status: string;
  created_at: string;
  settings: {
    allow_retakes: boolean;
    time_limit: number;
    send_results_email: boolean;
    require_consent: boolean;
  };
}

const campaignData: CampaignCreateRequest = {
  name: "Q2 2024 Leadership Assessment",
  description: "Comprehensive leadership evaluation",
  settings: {
    allow_retakes: false,
    time_limit: 3600
  }
};

const response = await fetch('https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/create', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer deepsy-dev-your-api-key-here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(campaignData)
});

const newCampaign: CampaignCreateResponse = await response.json();
console.log(newCampaign);

PHP

<?php
$campaignData = [
    'name' => 'Q2 2024 Leadership Assessment',
    'description' => 'Comprehensive leadership evaluation',
    'settings' => [
        'allow_retakes' => false,
        'time_limit' => 3600
    ]
];

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_URL => 'https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/create',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($campaignData),
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer deepsy-dev-your-api-key-here',
        'Content-Type: application/json'
    ],
]);

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

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

Response

{
  "campaign_id": "camp_987654321",
  "name": "Q2 2024 Leadership Assessment",
  "description": "Comprehensive leadership evaluation",
  "status": "draft",
  "created_at": "2023-01-20T00:00:00Z",
  "settings": {
    "allow_retakes": false,
    "time_limit": 3600,
    "send_results_email": true,
    "require_consent": true
  }
}

Get Campaign Details

Retrieve detailed information about a specific campaign.

Endpoint

GET /campaign/{company_id}/{campaign_id}/get-details

Example Request

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

Response

{
  "campaign_id": "camp_123456789",
  "name": "Q1 2024 Recruitment Campaign",
  "description": "Psychological assessment for new hires",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z",
  "updated_at": "2023-01-15T10:30:00Z",
  "settings": {
    "allow_retakes": false,
    "time_limit": 3600,
    "send_results_email": true,
    "require_consent": true
  },
  "statistics": {
    "total_invitations": 30,
    "completed_assessments": 25,
    "completion_rate": 83.3,
    "average_score": 78.5
  },
  "tests": [
    {
      "test_id": "personality_assessment",
      "name": "Personality Assessment",
      "duration": 1200
    }
  ]
}

Update Campaign

Modify an existing campaign's details and settings.

Endpoint

PUT /campaign/{company_id}/{campaign_id}/update

Request Body

{
  "name": "Updated Campaign Name",
  "description": "Updated description",
  "status": "active",
  "settings": {
    "allow_retakes": true,
    "time_limit": 4800
  }
}

Example Request

curl -X PUT "https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/camp_123456789/update" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Campaign Name",
    "status": "active"
  }'

Bulk Archive Campaigns

Archive multiple campaigns at once for organizational purposes.

Endpoint

POST /campaign/{company_id}/bulk-archive

Request Body

{
  "campaign_ids": [
    "camp_123456789",
    "camp_987654321",
    "camp_555666777"
  ]
}

Example Request

curl -X POST "https://deepsy.fr/api/v1/campaign/c193a06f-1c25-4e65-84a7-95faaae7ae7b/bulk-archive" \
  -H "Authorization: Bearer deepsy-dev-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_ids": ["camp_123456789", "camp_987654321"]
  }'

Campaign Invitations

Manage candidate invitations for your campaigns.

List Campaign Invitations

GET /campaign/{company_id}/{campaign_id}/invitations/list

Create Campaign Invitation

POST /campaign/{company_id}/{campaign_id}/invitations/create

Request Body

{
  "email": "candidate@example.com",
  "first_name": "Jane",
  "last_name": "Smith",
  "message": "You're invited to complete our assessment",
  "send_email": true
}

Bulk Create Invitations

POST /campaign/{company_id}/{campaign_id}/invitations/bulk-invitations

Request Body

{
  "invitations": [
    {
      "email": "candidate1@example.com",
      "first_name": "John",
      "last_name": "Doe"
    },
    {
      "email": "candidate2@example.com",
      "first_name": "Jane",
      "last_name": "Smith"
    }
  ],
  "send_emails": true,
  "message": "Welcome to our assessment process"
}

Send Email Invitation

POST /campaign/{company_id}/{campaign_id}/invitations/{invitation_id}/send-email-invitation

Delete Invitation

DELETE /campaign/{company_id}/{campaign_id}/invitations/{invitation_id}/delete

Bulk Delete Invitations

POST /campaign/{company_id}/{campaign_id}/invitations/bulk-delete

Campaign Assets

Manage files and assets associated with your campaigns.

Upload Asset

POST /campaign-assets/{company_id}/upload

List Assets

GET /campaign-assets/{company_id}/list

Get Asset

GET /campaign-assets/{company_id}/{asset_id}

Replace Asset

PUT /campaign-assets/{company_id}/{asset_id}/replace

Rename Asset

PUT /campaign-assets/{company_id}/{asset_id}/rename

Access Asset File

GET /campaign-assets/{asset_id}/{file_path}

Campaign Statuses

Status	Description
draft	Campaign is being created/configured
active	Campaign is live and accepting responses
paused	Campaign is temporarily stopped
completed	Campaign has finished
archived	Campaign is archived for historical purposes

Interactive Campaign Status Tracker

Use this interactive tool to track and manage your campaign statuses. You can add campaigns, update their status, and monitor completion rates.

Campaign Status Tracker

Track and manage your campaign statuses interactively

Add New Campaign

DraftActivePausedCompletedArchived

Your Campaigns

Q1 2024 Leadership Assessment

Status:DraftActivePausedCompletedArchivedCampaign is live and accepting responses

Invitations:50

Completed:35

Completion Rate:70.0%

Technical Skills Evaluation

Status:DraftActivePausedCompletedArchivedCampaign is being created/configured

Invitations:0

Completed:0

Completion Rate:0.0%

Status Legend

DraftCampaign is being created/configured

ActiveCampaign is live and accepting responses

PausedCampaign is temporarily stopped

CompletedCampaign has finished

ArchivedCampaign is archived for historical purposes

Best Practices

1. Campaign Planning: Plan your campaigns thoroughly before activation
2. Bulk Operations: Use bulk operations for efficiency when managing multiple items
3. Asset Management: Organize campaign assets with clear naming conventions
4. Invitation Tracking: Monitor invitation delivery and response rates
5. Regular Updates: Keep campaign information current and relevant

Related Guides

• Candidate Management Guide - Manage assessment results and reporting
• Company Users Guide - Manage company users and memberships
• Permissions Guide - Understand required permissions
• Error Handling Guide - Handle API errors effectively