Articles in this section

Receiving a Candidate

Avatar
Integrations Platforms
Updated
Follow

This will be a route on the receiving application or integration and not the candidate hub. This route will accept standard candidate data and return a standard response to be consumed by the hub.

If parsing is enabled, two additional candidate documents will be included. The raw parsed XML as a "tagged_cv" and a JSON document of type "parsed_cv" (both Base64 encoded).

Parsed CV example:

{ "email": "candidate@hotmail.com", "last_name": "Frog", "first_name": "Leap", "locale": "en_gb", "street": "4 Apple Croft", "country": "England", "county": "West Midlands", "post_code": "CW3 9EW", "town": "Madeley", "skills": [ { "skill_name": "meeting facilitation", "experience": 2 } ] }

Request

 
POST https://url_of_your_candidate_importer.com/importer_route
Headers
  • Content-Type:application/json
Body

{
    "meta_info" : { 
        "hub_transaction_id" : "UniqueHubTransactionId",
        "hub_client_id" : "ClientIDFromCandidateHub",
        "hub_candidate_id" : "CandidateIDFromHub",
        "hub_source_id" : "SourceIDFromHub",
        "hub_schema_version" : 1,
        "import_process_report_url" : "http://candidatehub.adcourier.com/report/onetimetoken" # Report of processing to this URL
    },
    "candidate" : {
        "name" : "John Renbourn",
        "email" : "john@renbourn.com",
        "contact_telephone" : "0123 456 7890", 
        "mobile_telephone" : "0123 456 7890", 
        "location_address" : "Address Details", 
        "location_city" : "Edinburgh",
        "location_county" : "Leith", 
        "location_country" : "Scotland", 
        "location_postcode" : "EH6 4AU", 
        "location_longitude" : "-0.564736", 
        "location_latitude" : "51.803398", 
        "current_job_title" : "Guitar Maestro", 
        "current_job_employer" : "Broadbean Technology", 
        "current_job_startdate" : "1944-08-08T00:00:00", 
        "current_job_enddate" : "2015-03-26T00:00:00", 
        "documents" : [
            { 
                "filename" : "blah.doc",
                "type" : "cv",
                "content" : "base64"
            },
            {
                "filename" : "blah.xml",
                "type" : "tagged_cv",
                "content" : "base64"
            },
            {
                "filename" : "blah.json",
                "type" : "parsed_cv",
                "content" : "base64" 
            }
        ]
    },
    "context" : {
        "job_id" : "129",
        "shortlist_id" : "869",
        "supplementary" : {
            "arbitrary_context_1" : "12",
            "arbitrary_context_2" : "13"
        }
    },
    "authentication" : {
        "api_key"   : "apiKey1",
        "time"      : "1594796637012",
        "signature" : "90f794a2d7cc174dcae31a901123bbde38ec43f82d86b8ef58e86e9ed6693e66"
    }
}

Response

Example of the response we expect from your system.

Headers
  • Content-Type:application/json
Body
{
  "success": 1,
  "message": "Candidate Received for processing"
}

 

Payload Fields

Field
Description
Mandatory
meta_info
Meta Info used to identify the specific request/payload
 Y
candidate
See Candidate Entity for a detailed description on how to populate this node
Y
context

See Candidate Context for detailed description on what this node includes

 N
authentication

Authentication details used to verify the request/payload came from CandidateHub

 N

 

Meta Info

Field
Description
Mandatory
hub_transaction_id
Unique ID for a Transaction in CandidateHub
 Y
hub_candidate_id Unique ID for a Candidate application  Y
hub_client_id ID for the client as setup in CandidateHub Y 
hub_source_id ID for the source as setup in CandidateHub. For source tracking you may want to use details from Candidate Context instead Y 
import_process_report_url Used to send a Candidate Processing Report callback after the candidate import has been processed on the receiving system  Y

  

Authentication

Field
Description
Mandatory
api_key
The API Key used to generate the signature. This is provided by Broadbean at the time of setup
 Y
time The time at which the signature was generated Y
signature

The unique request signature which you should verify to ensure the request came from CandidateHub. See Verifying the authentication/signature for details on how verify this.

 Y

 

Verifying the authentication/signature

To verify the signature you will need to generate it again and make sure it matches the one in the payload
  1. Obtain secret from Broadbean. eg: 1secret1
  2. Obtain api_key from payload eg: apiKey1
  3. Obtain time ( time signature was generated ) from the payload, this is an epoch timestamp in ms. eg: 1594796637012 ( Wednesday, 15 July 2020 07:03:57.012 GMT )
  4. Concatenate api_key and time separated by a pipe. eg: apiKey1|1594796637012
  5. HMAC-SHA256 encode the concatenated string with the secret from Broadbean.
Example using Bash and OpenSSL:
# Usage: echo -n {api_key}|{time} | openssl dgst -sha256 -hmac {secret}

echo -n 'apiKey1|1594796637012' | openssl dgst -sha256 -hmac 1secret1

# Output:
(stdin)= 90f794a2d7cc174dcae31a901123bbde38ec43f82d86b8ef58e86e9ed6693e66

  6. The secret key in this example would be  90f794a2d7cc174dcae31a901123bbde38ec43f82d86b8ef58e86e9ed6693e66 and should match the the /authentication/signature value in the payload

Related articles