Candidate

Overview

POST
https://api-external.domain.com/api/anonymous/candidate

This document provides detailed information on how to use the Candidate Creation endpoint. This API allows you to create a new candidate in the system.

Request Body

{
  "ExternalId": "string",
  "Email": "string",
  "FirstName": "string",
  "LastName": "string",
  "Preposition": "string",
  "Gender": integer,
  "NeedsToUpdateData": boolean
}

Field Descriptions

Field	Type	Required	Description
ExternalId	string	Yes	A unique identifier for the candidate. Must be unique across the system.
Email	string	Yes	The candidate's email address. Must be a valid email format and at least 5 characters long.
FirstName	string	Yes	The candidate's first name. Must contain at least 2 characters.
LastName	string	Yes	The candidate's last name. Must contain at least 2 characters.
Preposition	string	Yes	Any prepositions in the candidate's name (e.g., "van", "de"). If none, provide an empty string "".
Gender	integer	Optional	The candidate's gender. If unknown or cannot be provided, use 0 (Unknown).
NeedsToUpdateData	boolean	Optional	Indicates whether the candidate should be prompted to update their data upon starting the assessment. Defaults to false if not provided.

Gender Options

Value	Description
0	Unknown - will prompt the user to set their gender on creating the assessment.
1	Male
2	Female
3	Neutral

Response

Success Response

Status Code: 201 Created

Response Body

{
  "StatusCode": 201,
  "Message": null,
  "Data": {
    "ExternalId": "john.williams"
  }
}

Error Responses

Bad Request

Status Code: 400 Bad Request

Example Response

{
  "error": {
    "code": "ExternalIdAlreadyExists",
    "message": "The provided ID already exists",
    "innererror": {}
  }
}

Unauthorized

• Status Code: 401 The provided API key is not valid
• Status Code: 401 Invalid username or password

Additional Information

• All fields are required, except for Gender and NeedsToUpdateData, which are optional.
• ExternalId must be unique across the system. Attempting to use an ExternalId that already exists will result in a 400 Bad Request error.
• FirstName and LastName must each contain at least 2 characters.
• Email must be a valid email address format and at least 5 characters long.
• If Gender is not provided or is unknown, use 0 (Unknown). The candidate will be prompted to set their gender before starting the assessment.
• NeedsToUpdateData is a boolean flag. If set to true, the candidate will be prompted to update their data upon starting the assessment. Even when this flag is true, all data fields must still be provided in the initial request, although this data will not be shown to the candidate.

Examples

Example Request

POST /api/anonymous/candidate HTTP/1.1
Host: api.example.com
Content-Type: application/json
Authorization: Basic am9objpzdXBlcnNlY3JldA==
api-key: your_api_key_here

{
  "ExternalId": "john.williams",
  "Email": "[email protected]",
  "FirstName": "John",
  "LastName": "Williams",
  "Preposition": "",
  "Gender": 0,
  "NeedsToUpdateData": true
}

Example Success Response

HTTP/1.1 201 Created
Content-Type: application/json

{
  "StatusCode": 201,
  "Message": null,
  "Data": {
    "ExternalId": "john.williams"
  }
}

Example Error Response (ExternalId Already Exists)

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": "ExternalIdAlreadyExists",
    "message": "The provided ID already exists",
    "innererror": {}
  }
}

For any further clarification, please refer to Understanding Authentication and Authorization in Our API or contact our support team.