RefappRefapp

Submit a candidate

View as Markdown
POSThttps://{host}/webhooks/ats-generic

Creates 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-eventobjectrequired
    Show properties
    • idstring
    • companyobjectrequired
      Show properties
      • namestring | null
      • uuidstringrequired
      • ats-urlstring | null
    • candidateobjectrequired
      Show properties
      • idnumber | stringrequired
      • first-namestring | null
      • last-namestring | null
      • emailstring | null
      • phonestring | null
      • country-calling-codestring | null
      • refereesarray of object | null
        Show item properties
        • first-namestring | null
        • last-namestring | null
        • emailstring | null
        • phonestring | null
        • country-calling-codestring | null
        • languagestring | null
      • employment-historyarray of object | null
        Show item properties
        • organisationstringrequired
          minLength: 1
        • positionstring | null
          minLength: 1
        • startstringrequired
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
        • endstring | null
          pattern: ^\d{4}-(0[1-9]|1[0-2])$
        • is-currentboolean | null
      • recruiterobjectrequired
        Show 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 | null
          Show alternatives
          • Alternative 1string
          • Alternative 2array of string
      • jobobjectrequired
        Show properties
        • idnumber | stringrequired
        • alternate-idsarray of number | string | null
        • titlestringrequired
        • private-titleboolean | null
        • client-namestring | null
        • recruiting-teamarray of object | null
          Show 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 | null
            Show 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-resultobjectrequired
      Show properties
      • idstringrequired
      • statusstring
        One of "sending", "sent", "pending", "completed", "failed"
      • update-urlstring | null
    • webhook-dataobject | null
      Show properties
      • (any other key)string | boolean | number

Responses

201application/json

Received. data is present when the candidate was created or found, errorMessage when Refapp could not act on the request.

Show response body
  • messagestringrequired
  • dataobject
    Show properties
    • typestringrequired
      Always "partner-results"
    • idstringrequired
    • attributesobjectrequired
      Show properties
      • statusstringrequired
        One of "sending", "sent", "pending", "completed", "failed"
      • summarystringrequired
      • urlstring
      • candidateLinkobject
        Show properties
        • urlstringrequired
        • descriptionstringrequired
        • typestring
          One of "report-url", "report-pdf-data", "candidate-url"
      • candidateSubmissionPageLinkobject
        Show properties
        • urlstringrequired
        • descriptionstringrequired
        • typestring
          One of "report-url", "report-pdf-data", "candidate-url"
      • assessmentobject
        Show properties
        • typestring
          Always "reference-check"
        • scorenumber
        • totalnumber
        • remainingToSubmitnumber
        • completednumber
        • declinednumber
        • fraudWarningsarray of string
      • attachmentsarray of object
        Show item properties
        • urlstringrequired
        • descriptionstringrequired
        • typestring
          One of "report-url", "report-pdf-data", "candidate-url"
      • criteriaobject

        Values to route the candidate on, keyed by criterion id. moving_criteria in GET /webhooks/ats-generic/config is 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_outcomestring

          Where the background check stands. anomalies_* once it found anomalies: pending until a reviewer approves or rejects them. declined when the candidate declined. More values can be added.

          One of "in_progress", "clear", "anomalies_pending_review", "anomalies_approved", "anomalies_rejected", "declined"
        • reference_check_fraudstring

          warning while a fraud warning is active on the candidate. More values can be added.

          One of "positive", "warning"
        • reference_check_referees_overduestring

          overdue once 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_behavioursstring

          warning when a behavioural trait fell outside the target range, insufficient when too few referees answered to compare against the benchmark. More values can be added.

          One of "positive", "warning", "insufficient"
        • reference_check_cwbstring

          warning when a referee reported a counterproductive work behaviour. More values can be added.

          One of "positive", "warning"
        • reference_check_recommendationnumber

          How strongly the referees recommend the candidate, in percent.

          minimum: 0 · maximum: 100
        • (any other key)string | number
      • detailsobject

        Text in the account's language to show to a recruiter. The keys are names and labels, which can change. Routing rules must use criteria, not details.

        Show properties
        • (any other key)string | object
          Show alternatives
          • Alternative 1string
          • Alternative 2object
            Show 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": {}
}
401text/plain

The token is missing, unknown, revoked, or the integration is not enabled for the account. All four look the same.