Appearance
Create a candidate
POST
/api/nova/candidates
Creates a new candidate from the JSON request body. Supported fields include first and last name, email addresses, phone numbers, social profile links, date of birth, overview, internal notes, skills, tags (group and value pairs, matching the shape returned by candidate reads), work permit, right to work and do-not-contact flags, rating, ownerId (unknown ids are ignored and ownership defaults to the API user), statusId and sourceId master data references, education history, employment history, and custom (UDF) field values. The create counts towards the account's candidate record limit. A duplicate check runs before the record is created: an existing candidate matching on email, LinkedIn profile, or first name, surname and current employer combination blocks the create and responds with 409, carrying the existing candidate's ID in the data field so it can be updated instead. Returns the new candidate's ID on success, 401 for an invalid API key, and 429 when the record limit or rate limit is exceeded.
Authorizations
privateApiKey
Type
API Key (query: apiKey)
Parameters
Query Parameters
apiKey*
apiKey
Type
Requiredstring
Request Body
application/json
JSON "alternateEmail": "string", "currentEmployer": "string", "customFields": [ { "boolValue": "string", "dateValue": "string", "fieldId": "string", "fieldLabel": "string", "listValue": [ "string" ], "value": "string" } ], "dateOfBirth": "string", "doNotContact": true, "educationHistory": [ { "educationLevelId": "string", "endYear": 0, "grade": "string", "major": "string", "organisation": "string", "startYear": 0 } ], "email": "string", "employmentHistory": [ { "companyName": "string", "employmentTypeId": "string", "endDate": "string", "jobTitle": "string", "startDate": "string", "workSummary": "string" } ], "facebook": "string", "firstName": "string", "homePhone": "string", "id": "string", "internalNotes": "string", "jobTitle": "string", "lastName": "string", "linkedIn": "string", "mobile": "string", "overview": "string", "ownerId": "string", "rating": 0, "rightToWork": true, "skills": [ "string" ], "sourceId": "string", "statusId": "string", "tags": [ { "group": "string", "value": "string" } ], "twitter": "string", "workPermit": true, "workPhone": "string"
{
}
Responses
OK
application/json
JSON "data": "string", "error": "string", "message": "string", "requestId": "string", "success": true
{
}