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 Veritone Hire)
|
Generating X-CHUB-SIGNATURE:
Example of creating X-CHUB-SIGNATURE Header:
- Obtain secret from Veritone Hire. eg: secret
- Obtain source ID from Veritone Hire. eg: board1
- Generate an EPOCH Time. eg: 1577965016 (Thursday, 2 January 2020 11:36:56)
- Concatenate Source ID and EPOCH Time, separated by a pipe. eg: board1|1577965016
- HMAC-SHA256 encode the concatenated string with the secret from Veritone Hire.
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 Veritone Hire)
|
Y |
source_id
|
Transaction/Publisher Source ID to link to the transformer (Provided by Veritone Hire) | 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 Veritone Hire account is not set up for Candidate hub | 403 |
Client 'Foo' is not active" | Field ClientID in the transaction field is incorrect or your Veritone Hire 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 |