SmartRecruiters - Assessments Setup Guide

This guide is for assessment providers who want to offer their assessments to SmartRecruiters customers through Knit. Setup has two parts:

• Part 1 - Partnership Configuration: a one-time setup between you, SmartRecruiters and Knit.
• Part 2 - Per-Customer Connection: repeated every time a SmartRecruiters customer connects to your assessment product.

Part 1: Partnership Configuration (one-time)

1. Request partner credentials from SmartRecruiters

Contact the SmartRecruiters Partner team and share:

• The list of scopes you need access to on behalf of customers.
• Your app listing details: logo, short description, full description, and a plain-language description of what data you access and why. This is shown to customers before they connect (see Part 2).

On approval, SmartRecruiters issues a master clientId and clientSecret to you. For more details, refer to the SmartRecruiters Integration Workflow.

2. Register your partner credentials with Knit

Use the Register ATS Assessment Partner Credentials API to share the master credentials from Step 1 with Knit. Knit uses them to complete the connection with SmartRecruiters on behalf of your customers.

3. Generate a partner-level access token

Generate an access token using the master credentials. This token is used as a Bearer token in the next step.

curl --request POST \
  --url 'https://api.smartrecruiters.com/identity/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data client_id=YOUR_CLIENT_ID \
  --data client_secret=YOUR_CLIENT_SECRET

4. Register your configuration with SmartRecruiters

Using the token from Step 3 as a Bearer token, call the savepartnerconfig API.

Values provided by Knit:

Values provided by you:

On success, the configuration is saved and the partnership is live.

5. Publish your assessment packages to Knit

Use the Update Assessment Packages API to upload the list of assessment packages you offer. Knit serves this list to SmartRecruiters through the assessmentPackageListUrl and singleAssessmentPackageUrl endpoints. Whenever your packages change, call this API again to keep SmartRecruiters in sync.

Every package needs the following fields, SmartRecruiters rejects packages that are missing any of them:

Part 2: Per-Customer Connection

Repeat these steps for every SmartRecruiters customer that connects to your assessment product.

1. Customer initiates the connection

The customer finds your app in the SmartRecruiters Apps & Integrations page (displayed using the listing details from Part 1, Step 1), reviews the scopes you requested, and approves them. SmartRecruiters then redirects the customer to your registered consentUrl, as a popup or a full redirect depending on your consentDisplayMode, and passes the customer's company as ?companyId={id}. This is SmartRecruiters' internal company id (for example 5f3a9c2e8b1d4c6f9a7e2d4b), not the company name or the identifier returned by other SmartRecruiters APIs.

2. Verify the customer and confirm consent

Your consentUrl page should confirm the customer's identity in your system and show them what SmartRecruiters data you will access.

Note: Confirm with the SmartRecruiters Partner team whether this page needs to call back to SmartRecruiters to formally record consent, or whether reaching this page is sufficient for the next step to succeed.

3. Register the customer with Knit

Once the customer is verified, call the Create ATS Assessment Secrets API with the SmartRecruiters companyId received in Step 1.

Note: This call must be made in the context of that customer's Knit integration, using your Bearer token and the customer's X-Knit-Integration-Id. The customer needs to have a SmartRecruiters integration set up with Knit before this step.

Note: Your partner credentials from Part 1, Step 2 must be registered first, otherwise this call fails with a "register partner credentials first" error. SmartRecruiters also rejects the exchange if the customer has not completed the consent step yet (403) or if the company is already connected (409).

4. Knit completes the exchange with SmartRecruiters

Knit calls the SmartRecruiters setupintegration API to exchange and confirm credentials for that companyId. No action is needed from you.

From this point the customer's assessment integration is active: SmartRecruiters can list your packages and place orders, and you can push results back through Knit.

Receiving Orders and Sending Results

• Orders: Once the customer completes their selection, SmartRecruiters places an order with a POST request to your packageOrderUrl. Knit triggers a record.new event for it, delivered to the webhook URL registered for the ATS category. See Supported Events below.
• Results: To report progress or results back to SmartRecruiters, use the Update Candidate Assessment API.

Supported Events - SmartRecruiters

record.new

The record.new event is triggered by Knit when SmartRecruiters sends a POST request to the /packages/orders endpoint (packageOrderUrl) to submit a customer's order. This event is sent to the webhook URL registered for the ATS category.

Use eventData.candidateAssessment.id as the candidateAssessmentId when reporting results with the Update Candidate Assessment API.

Note: SmartRecruiters only sends the candidate's id, email, firstName, lastName and applicationLanguage in the order, so phones, links and location are always null. It does not send an application ID, so applicationId is built as {candidateId}||{jobId}. The complete order sent by SmartRecruiters is available in originData.

Example Event Payload:

{
  "eventType": "record.new",
  "eventData": {
    "candidateAssessment": {
      "applicationId": "5f3a9c2e-8b1d-4c6f-9a7e-2d4b6c8e0f13||7c1e4d92-3a5b-4f68-b0d1-9e2a6c8f4b57",
      "assessmentPackage": {
        "description": null,
        "id": "pkg_9f3aK21",
        "metaData": null,
        "name": null,
        "type": null
      },
      "callbackUrl": "https://api.smartrecruiters.com/assessment-api/v202010/orders/3b8d6f1a-52c4-4e97-a0b3-7d9e1c2f6a48/results",
      "candidate": {
        "emails": [
          {
            "email": "[email protected]",
            "type": "NOT_SPECIFIED"
          }
        ],
        "firstName": "John",
        "id": "5f3a9c2e-8b1d-4c6f-9a7e-2d4b6c8e0f13",
        "lastName": "Doe",
        "links": null,
        "location": null,
        "phones": null
      },
      "id": "ats_ass_PkX8gRRNx05D1cKvomNCW5",
      "jobId": "7c1e4d92-3a5b-4f68-b0d1-9e2a6c8f4b57",
      "metaData": null,
      "originData": {
        "assessmentPackageId": "pkg_9f3aK21",
        "candidate": {
          "applicationLanguage": "en",
          "email": "[email protected]",
          "firstName": "John",
          "id": "5f3a9c2e-8b1d-4c6f-9a7e-2d4b6c8e0f13",
          "lastName": "Doe"
        },
        "companyId": "5f3a9c2e8b1d4c6f9a7e2d4b",
        "jobId": "7c1e4d92-3a5b-4f68-b0d1-9e2a6c8f4b57",
        "requester": {
          "email": "[email protected]",
          "userId": "2a7d5e81-6c3f-4b90-8e14-5f9a1d3c7b62"
        },
        "resultCallbackURL": "https://api.smartrecruiters.com/assessment-api/v202010/orders/3b8d6f1a-52c4-4e97-a0b3-7d9e1c2f6a48/results"
      },
      "status": "NOT_SPECIFIED"
    }
  },
  "eventId": "evt-1982736450012",
  "recordId": "ats_ass_PkX8gRRNx05D1cKvomNCW5",
  "syncType": "real_time",
  "syncDataType": "ats_assessments",
  "syncJobId": "real_time",
  "syncRunId": "real_time_1982736441123",
  "triggeredAt": 1982736450012
}

Resources

• SmartRecruiters Integration Workflow - detailed flow
• SmartRecruiters Customer Experience - what customers see when connecting