Candidates

This endpoint manages candidate profiles within the recruitment system.

Overview

The Candidates API provides functionality for creating and managing candidate profiles throughout the recruitment process. These profiles contain essential information about job applicants and track their progress through the hiring pipeline.

Key Features

Data Synchronization

This endpoint synchronizes with the IAM People service to maintain consistent personal information across systems. Core identity data (names, profile picture) is automatically kept in sync with the central IAM records.

Candidate Lifecycle

When a candidate is hired and becomes an employee, their candidate record is automatically deleted to avoid duplication, as they will now be managed through the Employees API.

Endpoints

get /api/v3/recruitment/candidates patch /api/v3/recruitment/candidates/:id/hire patch /api/v3/recruitment/candidates/:id/reject delete /api/v3/recruitment/candidates/:resource_id get /api/v3/recruitment/candidates/:resource_id post /api/v3/recruitment/candidates/create_candidates patch /api/v3/recruitment/candidates/move

get/api/v3/recruitment/candidates

Return a paginated list of recruitment/candidates

Input Schema

object
page?:
object
The page number, default to 1
number?: integer
The number of items per page, default to 1000
size?: integer
The sort order, comma separated list of fields. See sorting section for more details
sort?: string
Set to true to return the total number of items in the collection
count?: boolean
filter?:
object
id?: unknown
person_id?: unknown
organizational_unit?: unknown
facets?: unknown
first_name?: unknown
middle_name?: unknown
last_name?: unknown
picture_url?: unknown
secondary_email?: unknown
contact_number?: unknown
source?: unknown
status?: unknown
in_stage_at?: unknown
position_id?: unknown
stage_id?: unknown
created_by_id?: unknown
updated_by_id?: unknown
search?: unknown
person_id?: unknown
position_id?: unknown
The related resources to include in the response. Allowed resources are:
- `position`
- `stage`
included?:
array
Elements: string
The fields to include in the response.
The key is the resource type and the value is an array of fields.
fields?:
dictionary
Values: array

Typescript

type InputSchema = {
  page?: {
    // The page number, default to 1
    number?: number;
    // The number of items per page, default to 1000
    size?: number;
  };
  // The sort order, comma separated list of fields. See sorting section for more details
  sort?: string;
  // Set to true to return the total number of items in the collection
  count?: boolean;
  filter?: {
    id?: any;
    person_id?: any;
    organizational_unit?: any;
    facets?: any;
    first_name?: any;
    middle_name?: any;
    last_name?: any;
    picture_url?: any;
    secondary_email?: any;
    contact_number?: any;
    source?: any;
    status?: any;
    in_stage_at?: any;
    position_id?: any;
    stage_id?: any;
    created_by_id?: any;
    updated_by_id?: any;
    search?: any;
    person_id?: any;
    position_id?: any;
  };
  // The related resources to include in the response. Allowed resources are:
  // - `position`
  // - `stage`
  included?: Array<string>;
  // The fields to include in the response.
  // The key is the resource type and the value is an array of fields.
  fields?: { [key: string]: Array<any> };
};

Output Schema

object
data:
array
Elements:
object
type: string
id?: string
attributes?:
object
id?: integer
person_id?: integer
organizational_unit?: string
facets?: array
first_name?: string
middle_name?: string
last_name?: string
picture_url?: string or null
secondary_email?: string or null
contact_number?: string or null
source?: string
status?: string
in_stage_at?: datetime
created_by_id?: integer
updated_by_id?: integer
relationships?: open struct
included?:
array
Elements: open struct

Typescript

type OutputSchema = {
  data: Array<{
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      person_id?: number;
      organizational_unit?: string;
      facets?: Array<any>;
      first_name?: string;
      middle_name?: string;
      last_name?: string;
      picture_url?: string | null;
      secondary_email?: string | null;
      contact_number?: string | null;
      source?: string;
      status?: string;
      in_stage_at?: Date;
      created_by_id?: number;
      updated_by_id?: number;
    };
    relationships?: Record<string, any>;
  }>;
  included?: Array<Record<string, any>>;
};

patch/api/v3/recruitment/candidates/:id/hire

Decide to hire a candidate in position’s stage

Input Schema

object
id: unknown

Typescript

type InputSchema = { id: any };

patch/api/v3/recruitment/candidates/:id/reject

Decide to reject a candidate in position’s stage

Input Schema

object
id: unknown

Typescript

type InputSchema = { id: any };

delete/api/v3/recruitment/candidates/:resource_id

Delete the recruitment/candidates

Input Schema

object
resource_id: integer

Typescript

type InputSchema = { resource_id: number };

get/api/v3/recruitment/candidates/:resource_id

Show a specific recruitment/candidates

Input Schema

object
resource_id: integer
included?:
array
Elements: string
fields?:
dictionary
Values: array

Typescript

type InputSchema = {
  resource_id: number;
  included?: Array<string>;
  fields?: { [key: string]: Array<any> };
};

Output Schema

object
data:
object
type: string
id?: string
attributes?:
object
id?: integer
person_id?: integer
organizational_unit?: string
facets?: array
first_name?: string
middle_name?: string
last_name?: string
picture_url?: string or null
secondary_email?: string or null
contact_number?: string or null
source?: string
status?: string
in_stage_at?: datetime
created_by_id?: integer
updated_by_id?: integer
relationships?: open struct
included?:
array
Elements: open struct

Typescript

type OutputSchema = {
  data: {
    type: string;
    id?: string;
    attributes?: {
      id?: number;
      person_id?: number;
      organizational_unit?: string;
      facets?: Array<any>;
      first_name?: string;
      middle_name?: string;
      last_name?: string;
      picture_url?: string | null;
      secondary_email?: string | null;
      contact_number?: string | null;
      source?: string;
      status?: string;
      in_stage_at?: Date;
      created_by_id?: number;
      updated_by_id?: number;
    };
    relationships?: Record<string, any>;
  };
  included?: Array<Record<string, any>>;
};

post/api/v3/recruitment/candidates/create_candidates

Create candidate(s)

Input Schema

object
data:
array
Elements:
object
type: string
attributes: open struct
position_id: integer
stage_id: integer

Typescript

type InputSchema = {
  data: Array<{ type: string; attributes: Record<string, any> }>;
  position_id: number;
  stage_id: number;
};

patch/api/v3/recruitment/candidates/move

Move a candidate to a different stage

Input Schema

object
id: integer
stage_id: integer

Typescript

type InputSchema = { id: number; stage_id: number };