RefappRefapp

Reference check

View as Markdown

Send the candidate to Refapp to start the reference check. Refapp creates the candidate, and the project for the position if it does not exist yet, and depending on the chosen settings starts asking the candidate for referees by email or SMS.

#Request

POST https://test.refapp.se/webhooks/ats-generic
Authorization: Bearer <partner credential>
Content-Type: application/json

Only the Authorization header is needed. The customer is named inside the body, in company.uuid.

The endpoint behaves like a webhook receiver:

  • It is idempotent. The same request received twice takes no new action, because the candidate already exists.
  • It always answers 201 once the request has been received, whatever Refapp could do with it. To know whether it succeeded, look at the body: a data object with type equal to partner-results means the candidate was created or found; an errorMessage at the root means Refapp could not act.
{
  "partner-event": {
    "company": {
      "uuid": "yyy-customer-secret-yyy"
    },
    "candidate": {
      "id": "www",
      "first-name": "Alex",
      "last-name": "Lindqvist",
      "email": "alex.lindqvist@example.com",
      "phone": "+46701234567",
      "language": "sv",
      "job": {
        "id": "zzz",
        "title": "Full-stack web developer"
      },
      "recruiter": {
        "first-name": "Sam",
        "last-name": "Berg",
        "email": "sam.berg@yourcompany.example",
        "phone": "+46701234568"
      }
    },
    "partner-result": {
      "id": "vvv",
      "update-url": "https://app.partnersystem.example/reference-status"
    },
    "webhook-data": {
      "hide-project-name": false,
      "external-recruitment": false,
      "external-recruitment-customer": "",
      "external-recruitment-hide-customer": false,
      "form-sv": "JsRBfndvYDWNxE6Qm",
      "form-en": "F9aMavknzygEwTosh",
      "relation-verification": true,
      "referee-requests-choice": "email-sms",
      "num-referees-requested": "2",
      "referee-communication-automation": "email-sms"
    }
  }
}
MemberMeaning
partner-eventWraps everything.
company.uuidThe customer secret, the same value as the X-Provider-Key header in the configuration request. It selects the account.
candidate.idYour unique id for this reference checking process. Use the candidate's id in your system, or one per application if a candidate can be checked more than once.
candidate.jobThe position. id groups candidates into the same Refapp project; title names the project when Refapp creates it.
candidate.recruiterThe person handling the process. If the account allows it, Refapp provisions a user for them so communications can go out in their name.
partner-result.idYour id for the process on your side. Every status update carries it back.
partner-result.update-urlWhere Refapp pushes status updates.
webhook-dataThe recruiter's choices from the configuration form, keyed by field id. Which keys appear depends on the customer's settings.

Every field is described in the API reference.

For referee-requests-choice, your system may send the special value link. Refapp then creates the referee submission request without sending any email or SMS, as the "Copy web link" button does in Refapp, and returns the page's URL in candidateSubmissionPageLink inside attributes. Show that link to the candidate yourself.

#Giving more people access

To let more users see the reference check in Refapp, add a recruiting-team list to job. Each entry has the same shape as recruiter:

{
  "partner-event": {
    "company": { "uuid": "yyy-customer-secret-yyy" },
    "candidate": {
      "id": "www",
      "job": {
        "id": "zzz",
        "title": "Full-stack web developer",
        "recruiting-team": [
          {
            "first-name": "Sam",
            "last-name": "Berg",
            "email": "sam.berg@yourcompany.example",
            "phone": "+46701234568"
          }
        ]
      },
      "recruiter": {
        "email": "sam.berg@yourcompany.example"
      }
    },
    "partner-result": { "id": "vvv" }
  }
}

#Responses

#The candidate was created

The attributes object is the same status update Refapp will push to your update-url, so you do not have to parse it here; accepting the push is enough. Display texts come in the account's language, Swedish in this example, so they can be shown to the recruiter as they are.

{
  "message": "Handled Generic ATS for test partner data",
  "data": {
    "type": "partner-results",
    "id": "vvv",
    "attributes": {
      "status": "pending",
      "summary": "Kandidatens referenser håller på att samlas in – 0 av 2 är klara",
      "attachments": [
        {
          "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
          "description": "Länk till kandidat i Refapp"
        }
      ],
      "candidateLink": {
        "url": "https://test.refapp.se/candidate/DDDDDddddDddD9dD9",
        "description": "Länk till kandidat i Refapp"
      },
      "assessment": {
        "score": 0,
        "type": "reference-check",
        "total": 2,
        "remainingToSubmit": 2,
        "completed": 0,
        "fraudWarnings": []
      }
    }
  },
  "info": {
    "providerId": "yyy",
    "companyId": "Aa1a1AaaA1Aa1Aa1a",
    "added-new-users": "b2B2222BBBbbBBbBb",
    "added-project": "cCCcCcCcCcCccCcCC",
    "added-candidate": "DDDDDddddDddD9dD9"
  }
}

The info object is diagnostic and its contents may change; do not build on it.

#Refapp could not act

Here the recruiter's email domain is not allowed on the account:

{
  "message": "Handled Generic ATS for test partner data",
  "errorMessage": "invalid-email-domain",
  "localizableErrorMessage": "ATS_RECRUITER_EMAIL_DOMAIN_NOT_WHITELISTED",
  "info": {
    "companyId": "Aa1a1AaaA1Aa1Aa1a",
    "email": "sam.berg@yourcompany.example"
  }
}