Submit a candidate
https://{host}/webhooks/ats-genericCreates the candidate, and the project for candidate.job.id if it does not exist yet, on the account named by company.uuid. Idempotent: the same request again takes no new action. Answers 201 as soon as the request is received, whatever happened next; read data or errorMessage in the body to know.
Authentication
Authorization: Bearer <token>
The partner credential Refapp issued to your ATS. It identifies the vendor; the customer comes from X-Provider-Key or company.uuid.
Body
application/json, required
-
partner-eventobjectrequiredShow properties
-
idstring -
companyobjectrequiredShow properties
-
namestring | null -
uuidstringrequired -
ats-urlstring | null
-
-
candidateobjectrequiredShow properties
-
idnumber | stringrequired -
first-namestring | null -
last-namestring | null -
emailstring | null -
phonestring | null -
country-calling-codestring | null -
refereesarray of object | nullShow item properties
-
first-namestring | null -
last-namestring | null -
emailstring | null -
phonestring | null -
country-calling-codestring | null -
languagestring | null
-
-
employment-historyarray of object | nullShow item properties
-
organisationstringrequiredminLength: 1 -
positionstring | nullminLength: 1 -
startstringrequiredpattern: ^\d{4}-(0[1-9]|1[0-2])$ -
endstring | nullpattern: ^\d{4}-(0[1-9]|1[0-2])$ -
is-currentboolean | null
-
-
recruiterobjectrequiredShow properties
-
namestring | null -
first-namestring | null -
last-namestring | null -
emailstringrequired -
phonestring | null -
country-calling-codestring | null -
ats-urlstring | null -
external-user-identifierstring | array of string | nullShow alternatives
-
Alternative 1string -
Alternative 2array of string
-
-
-
jobobjectrequiredShow properties
-
idnumber | stringrequired -
alternate-idsarray of number | string | null -
titlestringrequired -
private-titleboolean | null -
client-namestring | null -
recruiting-teamarray of object | nullShow item properties
-
namestring | null -
first-namestring | null -
last-namestring | null -
emailstringrequired -
phonestring | null -
country-calling-codestring | null -
ats-urlstring | null -
external-user-identifierstring | array of string | nullShow alternatives
-
Alternative 1string -
Alternative 2array of string
-
-
-
ats-urlstring | null -
ats-public-keystring | null -
ats-namestring | null -
descriptionstring | null
-
-
languagestring | null -
ats-urlstring | null
-
-
partner-resultobjectrequiredShow properties
-
idstringrequired -
statusstringOne of"sending","sent","pending","completed","failed" -
update-urlstring | null
-
-
webhook-dataobject | nullShow properties
-
(any other key)string | boolean | number
-
-
Responses
Received. data is present when the candidate was created or found, errorMessage when Refapp could not act on the request.
Show response body
-
messagestringrequired -
dataobjectShow properties
-
typestringrequiredAlways"partner-results" -
idstringrequired -
attributesobjectrequiredShow properties
-
statusstringrequiredOne of"sending","sent","pending","completed","failed" -
summarystringrequired -
urlstring -
candidateLinkobjectShow properties
-
urlstringrequired -
descriptionstringrequired -
typestringOne of"report-url","report-pdf-data","candidate-url"
-
-
candidateSubmissionPageLinkobjectShow properties
-
urlstringrequired -
descriptionstringrequired -
typestringOne of"report-url","report-pdf-data","candidate-url"
-
-
assessmentobjectShow properties
-
typestringAlways"reference-check" -
scorenumber -
totalnumber -
remainingToSubmitnumber -
completednumber -
declinednumber -
fraudWarningsarray of string
-
-
attachmentsarray of objectShow item properties
-
urlstringrequired -
descriptionstringrequired -
typestringOne of"report-url","report-pdf-data","candidate-url"
-
-
criteriaobjectValues to route the candidate on, keyed by criterion id.
moving_criteriainGET /webhooks/ats-generic/configis the source of truth for the criteria and values that this account receives. This reference shows only the criteria and values that exist today. A criterion is left out until it has a value. Criteria and values can be added or removed at any time. Refapp avoids breaking changes, so a new criterion or value is more likely than a removed one or a changed value type. Ignore ids and values that you do not know.Show properties
-
background_check_outcomestringWhere the background check stands.
anomalies_*once it found anomalies: pending until a reviewer approves or rejects them.declinedwhen the candidate declined. More values can be added.One of"in_progress","clear","anomalies_pending_review","anomalies_approved","anomalies_rejected","declined" -
reference_check_fraudstringwarningwhile a fraud warning is active on the candidate. More values can be added.One of"positive","warning" -
reference_check_referees_overduestringoverdueonce the deadline for adding referees has passed and the candidate has not added all requested referees. More values can be added.One of"overdue","not_overdue" -
reference_check_behavioursstringwarningwhen a behavioural trait fell outside the target range,insufficientwhen too few referees answered to compare against the benchmark. More values can be added.One of"positive","warning","insufficient" -
reference_check_cwbstringwarningwhen a referee reported a counterproductive work behaviour. More values can be added.One of"positive","warning" -
reference_check_recommendationnumberHow strongly the referees recommend the candidate, in percent.
minimum: 0·maximum: 100 -
(any other key)string | number
-
-
detailsobjectText in the account's language to show to a recruiter. The keys are names and labels, which can change. Routing rules must use
criteria, notdetails.Show properties
-
(any other key)string | objectShow alternatives
-
Alternative 1string -
Alternative 2objectShow properties
-
(any other key)string
-
-
-
-
-
-
errorMessagestring -
localizableErrorMessagestring -
infoobject
Show example
{
"message": "string",
"data": {
"type": "partner-results",
"id": "string",
"attributes": {
"status": "sending",
"summary": "string",
"url": "string",
"candidateLink": {
"url": "string",
"description": "string",
"type": "report-url"
},
"candidateSubmissionPageLink": {
"url": "string",
"description": "string",
"type": "report-url"
},
"assessment": {
"type": "reference-check",
"score": 0,
"total": 0,
"remainingToSubmit": 0,
"completed": 0,
"declined": 0,
"fraudWarnings": [
"same-ip-address"
]
},
"attachments": [
{
"url": "string",
"description": "string",
"type": "report-url"
}
],
"criteria": {
"background_check_outcome": "in_progress",
"reference_check_fraud": "positive",
"reference_check_referees_overdue": "overdue",
"reference_check_behaviours": "positive",
"reference_check_cwb": "positive",
"reference_check_recommendation": 0
},
"details": {}
}
},
"errorMessage": "string",
"localizableErrorMessage": "string",
"info": {}
}The token is missing, unknown, revoked, or the integration is not enabled for the account. All four look the same.