Configuration

Before a recruiter starts a reference check, show them the settings Refapp
offers for their account: which questionnaire to use, whether to ask the
candidate for referees automatically, and so on. Refapp describes those
settings as form fields so you can render them in your own product without
knowing what each customer has configured.

The word recruiter here means the end user: someone who has, or will get, an
account in both Refapp and your system.

Request

GET https://test.refapp.se/webhooks/ats-generic/config

Two headers authenticate the call:

Header	Value
`Authorization`	`Bearer <partner credential>`
`X-Provider-Key`	The customer secret of the account being set up

Three query parameters shape the answer:

Parameter	Purpose
`job_id`	Your identifier for the position. If a matching project already exists in Refapp, the allowed settings are adapted to it.
`recruiter`	The recruiter's email address, so options can be limited to what that person may see, such as questionnaires of their unit.
`lang`	ISO 639-1 code of your interface language, so labels come back localised.

curl -H "Authorization: Bearer xxx-partner-credential-xxx" \
     -H "X-Provider-Key: yyy-customer-secret-yyy" \
     -d job_id=zzz \
     -d [email protected] \
     -d lang=en \
     -G "https://test.refapp.se/webhooks/ats-generic/config"

Response

The response is a list of form fields ready to render. Field types are
header, subheader, paragraph, select, checkbox and text. The first
three are labels with no value. A field may carry label-markdown or
label-html with a richer version of its label; use one of them when your
renderer can.

Every field's id becomes a key in the webhook-data you send when
submitting the candidate, with the value the
recruiter chose.

Treat the fields as dynamic content. Fields can be added or removed at any
time. Refapp avoids breaking changes, so a new field is more likely than a
removed field or a changed value type.

The exact shape of a field is in the
API reference. You can also see the settings a customer expects
in Refapp itself under Company Settings, Integrations, with the Preview button.

A customer with individual settings

{
  "config": {
    "fields": [
      {
        "id": "intro",
        "label": "Settings for this Refapp Reference Checking project.\nThis happens when a reference check is started for the first candidate for the position.",
        "type": "header",
        "disabled": true
      },
      {
        "id": "hide-project-name",
        "type": "checkbox",
        "label": "Hide the position name",
        "value": false
      },
      {
        "id": "external-recruitment-enabled",
        "type": "checkbox",
        "label": "External Recruitment",
        "value": true
      },
      {
        "id": "external-recruitment-customer",
        "type": "text",
        "label": "Client Name",
        "disabled": false,
        "value": ""
      },
      {
        "id": "external-recruitment-hide-customer",
        "type": "checkbox",
        "label": "Hide the client name",
        "value": false
      },
      {
        "id": "form-sv",
        "label": "Swedish Questions",
        "placeholder": "Select questions to ask referees that communicate in Swedish",
        "type": "select",
        "options": [
          { "id": "", "label": "None" },
          {
            "id": "B4y3buDWCMZusFnDY",
            "label": "Refapp standardmall - djupgående (21 questions)"
          },
          {
            "id": "JsRBfndvYDWNxE6Qm",
            "label": "Refapp standardmall - snabb (11 questions)"
          }
        ]
      },
      {
        "id": "form-en",
        "label": "English Questions",
        "placeholder": "Select questions to ask referees that communicate in English",
        "type": "select",
        "options": [
          { "id": "", "label": "None" },
          {
            "id": "9hRXxzddcAjYgpX5t",
            "label": "Refapp standard form - deep (21 questions)"
          },
          {
            "id": "F9aMavknzygEwTosh",
            "label": "Refapp standard form - quick (11 questions)"
          }
        ]
      },
      {
        "id": "relation-verification",
        "type": "checkbox",
        "label": "Request details on relationship from candidates and referees",
        "value": false
      },
      {
        "id": "intro-ref-req",
        "label": "Refapp Automation",
        "type": "header"
      },
      {
        "id": "referee-requests-choice",
        "label": "Ask candidates for referees via:",
        "type": "select",
        "value": "disabled",
        "options": [
          { "id": "disabled", "label": "Add referees manually in Refapp" },
          { "id": "sms", "label": "SMS" },
          { "id": "email", "label": "email" },
          { "id": "email-sms", "label": "email and SMS" }
        ]
      },
      {
        "id": "num-referees-requested",
        "label": "Requested referees",
        "type": "select",
        "options": [
          { "id": "1", "label": "1 referee" },
          { "id": "2", "label": "2 referees" },
          { "id": "3", "label": "3 referees" },
          { "id": "4", "label": "4 referees" },
          { "id": "5", "label": "5 referees" }
        ],
        "value": "3"
      },
      {
        "id": "referee-communication-automation",
        "label": "When a candidate has submitted a referee, automatically send a reference check via:",
        "type": "select",
        "value": "email-sms",
        "options": [
          {
            "id": "disabled",
            "label": "Send the reference check manually from Refapp"
          },
          { "id": "sms", "label": "SMS" },
          { "id": "email", "label": "email" },
          { "id": "email-sms", "label": "email and SMS" }
        ]
      }
    ]
  }
}

Render this as one form: headers as section titles, checkboxes and selects as
inputs with the given value preselected, and the text field as a free-text
input.

A customer using project templates

Some customers bundle all settings into templates. Then the whole form is one
select:

{
  "config": {
    "fields": [
      {
        "id": "project-template-id",
        "label": "Use this project template for all settings",
        "type": "select",
        "options": [
          {
            "id": "q7oDG65oqySpcxdfk",
            "label": "Intern rekrytering (svenska)"
          },
          { "id": "zKPgytXG9nChd4EPk", "label": "Simple External Recruitment" }
        ]
      }
    ]
  }
}

Routing criteria

The response can also hold moving_criteria. These are the values that
Refapp sends in criteria with each
status update. A recruiter can use them to build
rules that move a candidate to another stage, for example when a fraud warning
is active.

Each criterion has an id, a name and a kind. An outcome criterion lists
its possible outcomes, each with an id, a label and an optional hint. A
score criterion sends a number within its range. Names, labels and hints
are in the language of lang. Store your rules against the criterion id and
the outcome id. These stay the same while the criterion exists, but names and
labels can change.

Treat moving_criteria as dynamic content, like the fields. Criteria and
outcomes can be added or removed at any time, and the list follows the
settings of the customer's account. Refapp avoids breaking changes, so a new
criterion or outcome is more likely than a removed one or a changed value type.
The list is left out when the account has no criteria. Ignore a criterion or an
outcome that you do not know.

This list is the source of truth for the criteria and outcomes of an account.
Build your rules from it, not from the API reference. The
reference shows only the criteria and values that exist today.

{
  "config": {
    "fields": [
      {
        "id": "project-template-id",
        "label": "Use this project template for all settings",
        "type": "select",
        "options": [
          { "id": "zKPgytXG9nChd4EPk", "label": "Simple External Recruitment" }
        ]
      }
    ],
    "moving_criteria": [
      {
        "id": "reference_check_fraud",
        "name": "Fraud",
        "kind": "outcome",
        "outcomes": [
          {
            "id": "positive",
            "label": "No suspected fraud",
            "hint": "No fraud warning is active on this candidate."
          },
          {
            "id": "warning",
            "label": "Suspected fraud",
            "hint": "At least one fraud warning is active on this candidate."
          }
        ]
      },
      {
        "id": "reference_check_referees_overdue",
        "name": "Referee deadline",
        "kind": "outcome",
        "outcomes": [
          {
            "id": "overdue",
            "label": "Deadline for adding referees has passed",
            "hint": "The deadline has passed and the candidate has not added all requested referees."
          },
          {
            "id": "not_overdue",
            "label": "Not overdue",
            "hint": "The candidate has added all requested referees, or the deadline has not passed."
          }
        ]
      }
    ]
  }
}