Articles in this section

Sending a Candidate in

Avatar
Integrations Platforms
Updated
Follow

Overview

This route accepts a POST request consisting of a JSON payload and some authentication Headers. The response will consist of a success flag and either a transaction ID (success) or an error.

 

Endpoint Details

Endpoint: https://candidatehub.adcourier.com/candidate
Method: POST
Content-type: application/json

 

Authentication

Authentication is required for all requests to Candidate Hub. Authentication is sent via request headers in the following format.

Note: Signatures are valid for 5 mins, please ensure your system clock time is accurate.
HEADERS:
 'X-CHUB-SIGNATURE-TIME: 1577965016
 'X-CHUB-SOURCE: board1
 'X-CHUB-SIGNATURE: c57ed8130b75a69458416e9e91ac0baef604f8fce3bf1d7cf5bcb03d13af2765
Header
Description
X-CHUB-SIGNATURE-TIME
Epoch Unix time (seconds)
X-CHUB-SOURCE
Candidate Hub source ID
X-CHUB-SIGNATURE
HEX of HMAC-SHA256 (`SOURCE_ID`|`SIGNATURE_TIME_EPOCH`, `SECRET`) (Secret provided by Broadbean)
 

Generating X-CHUB-SIGNATURE:

Example of creating X-CHUB-SIGNATURE Header:
  1. Obtain secret from Broadbean. eg: secret
  2. Obtain source ID from Broadbean. eg: board1
  3. Generate an EPOCH Time. eg: 1577965016 (Thursday, 2 January 2020 11:36:56)
  4. Concatenate Source ID and EPOCH Time, separated by a pipe. eg: board1|1577965016
  5. HMAC-SHA256 encode the concatenated string with the secret from Broadbean.
Example using Bash and OpenSSL:
# Usage: echo -n {SOURCE_ID}|{SIGNATURE_TIME_EPOCH} | openssl dgst -sha256 -hmac {secret}

echo -n 'board1|1577965016' | openssl dgst -sha256 -hmac secret

# Output: (stdin)= c57ed8130b75a69458416e9e91ac0baef604f8fce3bf1d7cf5bcb03d13af2765

 

Request Body 

{
 "transaction": {
     "client_id": "123",
     "source_id": "native"
 },
 "candidate": {
     "name": "John 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": "<REDACTED BASE 64>"
      },
      {
       "filename": "cover_letter.pdf",
       "type": "coverletter",
       "content": "<REDACTED Base64 coverletter content>"
      }
    ]
 },
 "context": {
    "job_id": "123345",
    "shortlist_id": "869",
    "aplitrak_email_address": "cons.4567.312@dev.aplitrak.com"
  }
}

 

Top-level Fields

Field
Description
Mandatory
transaction
Transaction details to tie the candidate to the called
 Y
candidate
See Candidate Entity for a detailed description on how to populate this node
Y
context

Context related to the candidate application (e.g. how the candidate was sourced or job information)

 N

 

Transaction

Field
Description
Mandatory
client_id
ID for the candidate importer client mapper (Provided by Broadbean)
 Y
source_id
  Transaction/Publisher Source ID to link to the transformer (Provided by Broadbean)  Y

Context

Field
Description
Mandatory
job_id
The ID of the Job the candidate has applied to
 Y
shortlist_id Shortlist ID for the candidate N
aplitrak_email_address If you are a Job Board integrating with Candidate Hub, it is important that you include the unique tracking link/email in the supplementary context. This helps us identify the vacancy the candidate has applied for.

N


Response Body

{
   success: 1,
   hub_transaction_id: <guid>
}
{
   success: 0,
   error: clientId not known
}
Field
Description
success success boolean flag
hub_transaction_id unique GUID of successful request
error Error on unsuccessful request

 

Errors

Error
 Description
Code
No JSON present in the request. The request is missing a JSON body or the JSON is malformed 400
Client <your client> is not set up Field ClientID in the transaction field is incorrect or your Broadbean account is not set up for Candidate hub 403 
Client 'Foo' is not active" Field ClientID in the transaction field is incorrect or your Broadbean account is not active on Candidate hub 403 
Source 'Barr' is not set up Field `source_id` in the transaction field is incorrect or the source has not been configured in Candidate hub  400

 

Related articles