Candidate Entity

This page describes the format and data for a candidate record that you should expect to be able to use when Integrating with CandidateHub.

This is the standard format we expect to receive from all partners sending candidates into our system.

For partners receiving candidates from us, you should also expect to receive this format, however it is worth being aware that this is not a fixed schema.

CandidateHub has a list of Plugins available to help cater for client/partner specific requirements when receiving candidate data ( e.g. populating additional structured data from parsing of the candidate's CV attachment ). The broad intent is that we attempt to fit any additional data into this structure but at times we will need to extend this definition to accommodate specific use cases or requirements.

This standard list of data may be extended in the future to include additional commonly requested data.

Example Request 
{
    "name": "John Doe",
    "first_name": "John",
    "last_name": "Doe",
    "email": "tronan@applicant.com",
    "contact_telephone": "5555555555",
    "mobile_telephone": "5555555555",
    "location_city": "Austin, TX",
    "location_country": "US",
    "location_postcode": "78758",
    "location_latitude": "51.803398",
    "location_longitude": "-0.564736",
    "current_job_title": "Customer Success Manager",
    "current_job_employer": "CircleBack Inc",
    "current_job_startdate": "2013-07-01T12:00:00",
    "documents": [
        {
            "filename": "John_Doe.pdf",
            "type": "cv",
            "content": ""
        },
        {
            "filename": "cover_letter.txt",
            "type": "coverletter",
            "content": ""
        }
    ]
}
Field Description
Field Description Mandatory
name Name of candidate Y
first_name First name of candidate N
last_name Last name of candidate N
email The email address of the candidate Y
contact_telephone Primary contact telephone number N
mobile_telephone Mobile / Secondary contact telephone number N
location_address Location street address of Candidate Address N
location_city Location city of Candidate Address N
location_county Location county of Candidate Address N
location_country Location country of Candidate Address N
location_postcode Location Post/Zip code of Candidate Address N
location_latitude Location latitude of Candidate Address N
location_longitude Location longitude of Candidate Address N
current_job_title Current / Most Recent Job title N
current_job_employer Current / Most Recent Job employer N
current_job_startdate ISO 8601 formatted start date of current Employment N
current_job_enddate ISO 8601 formatted end date of current Employment N
documents One or more Document objects, including at least the Candidates CV

Y
education Zero or more Education objects

N
employment Zero or more Employment objects

N

Documents
Field Description Mandatory
filename Filename with extension Y
type Type of attachment ( 'cv', 'coverletter' ) Y
content Base64 encoded file contents Y
description Description of file N

Education
Field Description Mandatory
course Name of course N
major Name of major N
school Name of school N
summary Short description of course N
start_date ISO 8601 formatted start date of course N
end_date ISO 8601 formatted end date of course N
Employment
Field Description Mandatory
title Job title N
summary Short description of employment N
employer Name of employer N
start_date ISO 8601 formatted start date of employment N
end_date ISO 8601 formatted end date of employment N

Return to top