Guides

Integration Workflow

Suggest Edits

The section describes the steps in the integration process as well as the data exchange during the integration.

1. Connecting to SmartRecruiters

Before customers can utilize your service within the SmartRecruiters platform, SmartRecruiters, and your service will need to exchange credentials on two levels:

  • Partner level: The credential at this level is used to facilitate the customer-level credential exchange and for you to communicate your service endpoint to SmartRecruiters.
  • Customer level: The credentials at this level are for SmartRecruiters to query assessment packages, place orders onto your service, and for your service to retrieve job and candidate information, and submit assessment results to SmartRecruiters.

The SmartRecruiters – Assessment Partner Integration follows the OAuth 2.0 protocol and utilizes the Client Credential flow to exchange data with partners. We expect your team to be familiar with and have implemented the OAuth 2.0 protocol for your service, but if you have any questions regarding OAuth 2.0 Client Credential, please do not hesitate to reach out to our Partner Support team for more information.

You can also find more information on OAuth 2.0 Client Credential flow in this article.

1.1. Obtain Partner Level Credential

After you have provided SmartRecruiters with the materials, SmartRecruiters Partner Operations Team will review the requested data scope of your service. Once the review is completed, they will:

  1. Approve your system’s scope of access OR
  2. Require you to adjust to scope of access request based on the Principle of Least Privilege

When your requested access scope is approved, SmartRecruiters will also provide you a set of Partner Level credentials (master credentials) that will be used to validate your service’s identity and to facilitate Customer Level credential exchange in the future.

The master credential is a partner-specified clientId and clientSecret pair between SmartRecruiters and your service. A sample pair of master credentials look like this:

"clientId": "string"
"clientSecret": "string"

1.2. Configure URLs and Endpoints

In the early beta of this assessment API, the SmartRecruiters Partner Operation team will share the master credential with you and your team via encrypted email. Please store the credential safely.

After you receive the master credential, you can use them to exchange for an access token and use the token to configure the URLs and endpoints using SmartRecruiters /partner/configuration endpoint:

https://api.smartrecruiters.com/assessment-api/v202010/partner/configuration

Exchange your master credential for an access token before accessing /partner/configuration endpoint via:

https://api.smartrecruiters.com/identity/oauth/token

The token endpoint accepts the POST method. Below is an example request for exchanging the access token:

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

Once you have exchanged the access token, you can access the configuration endpoint. The /partner/configuration endpoint accepts the PUT method and expects the following payload:

{
  "consentUrl": "string",
  "consentDisplayMode": "REDIRECT",
  "assessmentPackageListUrl": "string",
  "singleAssessmentPackageUrl": "string",
  "packageOrderUrl": "string",
  "inlineAssessmentPackageOrderUrl": "string",
  "oauthTokenUrl": "string",
  "integrationDisableUrl": "string",
  "fields": [
    {
      "id": "string",
      "name": "string",
      "description": "string
    }
  ],
  "supportedAssessmentTypes": [
    "VIDEO_INTERVIEW"
  ]
}
  • consentUrl: The URL which SmartRecruiters will call in the /integration endpoint which redirects the customer's user to authenticate their identity for your service. SmartRecruiters will add companyId and redirect (when consentDisplayMode=REDIRECT) parameters when calling this page.
  • consentDisplayMode: This field determines the end-user experience during the integration activation step after the user authorized the access scope. There are only two acceptable values for this field:
    • REDIRECT: End users will leave SmartRecruiters and be redirected to the URL configured by the consentUrl field.
    • POPUP: End users will remain in SmartRecruiters and see a pop-up widget. The URL configured in the consentUrl will be displayed as the content of the widget.
  • assessmentPackageListUrl: An endpoint defined by your service which the SmartRecruiters service will call in the /packages endpoint to retrieve a list of assessment packages
  • singleAssessmentPackageUrl: An endpoint defined by your service which SmartRecruiters service will call in the /packages/{assesmentPackageId} endpoint to retrieve single package information.
  • packageOrderUrl: An endpoint defined by your service which SmartRecruiters will call as the /packages/orders endpoint to place an assessment order onto your service.
  • inlineAssessmentPackageOrderUrl: An endpoint defined by your service which SmartRecruiters will call as /packages/inline/orders. Similar to the packageOrderUrl, but for assessment order triggers during the candidate application phase. This endpoint value here can be the same as packageOrderUrl as long as your service can handle the different payloads when SmartRecruiters calls it. Leave this value empty if your service does not support customer users to order assessment during the application phase.
  • oauthTokenUrl: An endpoint defined by your service which SmartRecruiterassessmentss will call when to exchange the credential we received from your service for an access token to your endpoints.
  • integrationDisableUrl: An endpoint that your service specified to receive notifications on disabled integration for a specific customer.
  • fields: Optional fields specified by your services. If specified, customer admins can map SmartRecruiter's custom field values to your specified fields. SmartRecruiters will pass these fields and values as additional query parameters when we call the /packages endpoint. You can specify up to 5 fields:
    • fields.id: The identifier or name of the field which your service can process when SmartRecruiters pass this field and the corresponding value to your service in the /packages call.
    • fields.name: The user-friendly name of the field which will be displayed to the admin users to help them map a SmartRecruiters custom field.
    • fields.description: Description of the purpose of this field which will be displayed to the admin users to help them understand the meaning of the field.
  • supportedAssessmentTypes: The list of assessment types that your service supports. We accept the following types:
    • BACKGROUND_CHECK
    • BEHAVIORAL_ASSESSMENT
    • INLINE_ASSESSMENT
    • REFERENCE_CHECK
    • SKILL_TEST
    • VIDEO_INTERVIEW

Once your service makes a successful call to the /partner/configuration endpoint, SmartRecruiters will return the following payload:

{
  "consentUrl": "string",
  "consentDisplayMode": "REDIRECT",
  "assessmentPackageListUrl": "string",
  "singleAssessmentPackageUrl": "string",
  "packageOrderUrl": "string",
  "inlineAssessmentPackageOrderUrl": "string",
  "oauthTokenUrl": "string",
  "integrationDisableUrl": "string",
  "fields": [
    {
      "id": "string",
      "name": "string",
      "description": "string"
    }
  ],
  "supportedAssessmentTypes": [
    "VIDEO_INTERVIEW"
  ]
}

You may call the /partner/configuration endpoint again in cases where you need to make changes to the URLs or endpoints you had previously configured. You must include the access token you obtained in the previous step as the bearer token in the header when you make calls to the /partner/configuration endpoint.

1.3. Exchange Customer Level Credentials

When the customer initiates a connection request from SmartRecruiters to your service, your predefined access scope will be shown to the customers, and once the customer grants permission to the scope, the customer is redirected to your platform based on the consentURL you have provided in the earlier step.

{
  "consentUrl": "string",
  "consentDisplayMode": "REDIRECT",
  "assessmentPackageListUrl": "string",
  "singleAssessmentPackageUrl": "string",
  "packageOrderUrl": "string",
  "inlineAssessmentPackageOrderUrl": "string",
  "oauthTokenUrl": "string",
  "companyIntegrationUrl": "string",
  "fields": [
    {
      "id": "string",
      "name": "string",
      "description": "string"
    }
  ],
  "supportedAssessmentTypes": [
    "VIDEO_INTERVIEW"
  ]
}

SmartRecruiters will add URL query parameters when making a GET call to the page under consentUrl:

  • companyId containing a unique identifier for customers in SmartRecruiters
  • redirect, used only if your consentDisplayMode=REDIRECT, which your service should use to redirect users back to SmartRecruiters after the authorization step is completed

On your platform, the customer is expected to sign onto your service platform to authenticate his/her identity. There are two front-end implementation options:

  • SmartRecruiters provides a pop-up widget on the interface to load your service platform sign-in page.
  • SmartRecruiters redirect users to your sign-in page.

After your service authenticates the customer’s identity, you should present the scope of data access SmartRecruiters requires from your services for the integration to the customer.

Unless otherwise specified or discussed, the access scope SmartRecruiters requires on your platform will be the read access to the list of assessment packages the customer had created on your service platform.

Once the customer grants permission on SmartRecruiter's scope of access, your service should generate a customer-level credential and send them to SmartRecruiters with the SmartRecruiters /integration endpoint:

https://api.smartrecruiters.com/assessment-api/v202010/integration/company/{companyId}

Your customer-level credential should be a customer-specified clientId and clientSecret pair. An example of such credentials might look like this:

"clientId": "string"
"clientSecret": "string"

📘

Not to be confused with the master credentials from the above section

This set of credentials is for SmartRecruiters to access the customer’s data on your service.

🚧

ClientId uniqness

Generated clientId you send in this step must must be unique among all of your integrations.

You must include the master credentials access token you obtained in the previous step as the bearer token in the header when you make calls to the /integration endpoint.

When SmartRecruiters receives your set of credentials, SmartRecruiters will return a 200 OK response and pass your service back the SmartRecruiters customer level credential for your service to access the customer data in SmartRecruiters.

The SmartRecruiter customer-level credential is also a customer-specified clientId and clientSecret pair. A sample of the pair looks like this:

"clientId": "string"
"clientSecret": "string"

Based on the value configured in consentDisplayMode, end-user experience may differ:

  1. REDIRECT: If you choose the redirect approach, your service needs to handle the user frontend transition by sending users back to SmartRecruiters using the URL provided to you in the redirect parameter in the early step.

  2. POPUP: If you choose the pop-up widget approach, SmartRecruiters will handle the frontend user transition, closing the pop-up widget and refreshing the page.

At this point, the connection between SmartRecruiters and your service is set up for the customer. And similar to the master credentials, you can use the customer-level credential to exchange for an access token and use the token to access customer data in SmartRecruiters.

1284

Fig.1 Connecting to SmartRecuriters

2. Selecting Packages

After the connection is enabled between SmartRecrutiers and your service, the customer can begin ordering assessments from you. There are two ways the customer can order assessment packages:

  1. Manual one-time order for individual candidate profile
  2. Configured auto order for every candidate profile in specific hiring steps
    For every assessment package selection, SmartRecruiters will retrieve the package list from your service every time the customer wishes to order an assessment or when the customer configures the auto-order in a hiring step.

SmartRecruiters will call the /packages endpoint which is the assessmentPackageListUrl you previously specified on the /partner/configuration endpoint, through the GET method, to retrieve the list of available assessment packages to display to the customer:

https://${partner_domain_browse_package_url}

When SmartRecruiters make the above call, we will also pass along the assessment requester information via the header to help you determine the exact assessment package list to display to the assessment requester. The expected payload for the requester object in the header contains the following:

{
  "email": "string",
}

Additional information such as job location is also passed along as query parameters. If you configured fields using the /configuration endpoint and the customer had mapped SmartRecruiters customer fields to them, these fields and their respective SmartRecruiters custom field values will also be passed as an addition to the query parameters.

We expect your service to respond within the time of 15 seconds with the following response:

[
  {
    "id": "string",
    "type": "string",
    "name": "string",
    "description": "string",
    "assessments": [
      {
        "id": "string",
        "type": "string",
        "name": "string",
        "description": "string"
      }
    ]
  }
]

SmartRecruiters expects your service to return any alphanumeric value for the id, name, and description of both the package object and the assessments object. However, do note that for type, SmartRecruiters only accepts the following values:

  • BACKGROUND_CHECK
  • BEHAVIORAL_ASSESSMENT
  • INLINE_ASSESSMENT
  • REFERENCE_CHECK
  • SKILL_TEST
  • VIDEO_INTERVIEW

📘

Inline assessments

Package with type INLINE_ASSESSMENT will only show up when end users are configuring for inline assessment in the hiring process.

If your service does not distinguish an assessment package from an assessment, please return a list of assessments, with an empty assessment object, when SmartRecruiters calls the endpoint.

3. Creating Orders

Once the customer completes his/her selection, SmartRecruiters will place an order to the following endpoint specified by you, through the POST method, to submit the customer’s order:

https://${partner_domain_order_packages_url}

The /packages/orders endpoint is the packageOrderUrl which you specified with the /partner/configuration endpoint

SmartRecruiters will send over the following payload:

{
  "resultCallbackURL": "string",
  "candidate": {
    "id": "string",
    "email": "string",
    "firstName": "string", 
    "lastName": "string",
    "applicationLanguage": "string"
  },
  "requester": {
    "userId": "string",
    "email": "string"
  },
  "assessmentPackageId": "string",
  "jobId": "string",
  "companyId": "string"
}

In the payload, the resultCallbackURL is a unique identifier for an assessment order of SmartRecruiters.
SmartRecruiters expects your server to respond within the time of 15 seconds with HTTP 202 response.

If the customer user configured to trigger your service during the hiring step of the candidate application, SmartRecruiters calls the /packages/inline/orders endpoints, using the POST method, instead to place the assessment order onto your service:

https://${partner_domain_order_inline_pacakges_url}

Similar to the /packages/orders endpoint, the /packages/inline/orders endpoint is the inlineAssessmentPackageOrderUrl which you specified with the /partner/configuration endpoint.

SmartRecruiters will send over the following payload:

{
  "resultCallbackURL": "string",
  "candidate": {
    "email": "string",
    "firstName": "string",
    "lastName": "string",
    "applicationLanguage": "string"
  },
  "assessmentPackageId": "string",
  "jobId": "string",
  "companyId": "string",
  "completedAssessmentCallbackUrl": "string"
}

When your service received the order, SmartRecruiters expects it to respond within the time of 15 seconds with the following response:

{
  "url": "string"
}

The URL from your response is the URL to which SmartRecruiters will direct the candidate to take the assessment. After the candidate completed the assessment, your service can redirect the candidate back to SmartRecruiters by the completeAssessmentCallbackUrl.

1260

Fig. 2 Selecting and Ordering Assessments

4. Retrieving Resources

To help process the package order, your service can retrieve additional information about the candidate and job from SmartRecruiters candidate endpoint and job endpoint using the candidate_id, job_id and company_id passed to you.

Exchange your customer-level credential for an access token before accessing the candidate or job information via:

https://api.smartrecruiters.com/identity/oauth/token

4.1. Candidate Information

Retrieving additional candidate information using the GET method:

https://api.smartrecruiters.com/candidates/{id}

4.2. Job Information

Retrieving additional job information, including the company and department of the posted job using the GET method:

https://api.smartrecruiters.com/jobs/{jobId}

4.3. Hiring Team Information

Retrieving hiring team information using the GET method:

https://api.smartrecruiters.com/jobs/{jobId}/hiring-team

5. Updating Status and Results

5.1. Updating Package Status

To update the package's status, submit the status change to the resultCallbackURL from the response provided to you by the orders endpoints. Alternatively, you can update the package status by calling the SmartRecruiters /orders/{orderId}/results endpoint directly, using the PATCH method:

https://api.smartrecruiters.com/assessment-api/v202010/orders/{orderId}/results

The orderId is issued by SmartRecruiters, and you can find the orderId in the path of the resultCallbackURL.

We expect the following payloads:

{
  "assessmentDate": "2020-08-28T20:36:28.618Z",
  "submissionDate": "2020-08-28T20:36:28.618Z",
  "name": "string",
  "description": "string",
  "status": "IN_PROGRESS",
  "score": {
    "raw": 0,
    "min": 0,
    "max": 0
  },
  "scoreLabel": "string",
  "summary": "string",
  "attachments": [
    {
      "type": "VIDEO_URL",
      "url": "string"
    }
  ],
  "assessmentResults": [
    {
      "assessmentId": "string",
      "assessmentDate": "2020-08-28T20:36:28.618Z",
      "submissionDate": "2020-08-28T20:36:28.618Z",
      "score": {
        "raw": 0,
        "min": 0,
        "max": 0
      },
      "scoreLabel": "string",
      "summary": "string",
      "attachments": [
        {
          "type": "VIDEO_URL",
          "url": "string"
        }
      ],
      "status": "IN_PROGRESS"
    }
  ]
}

When the assessment package status changes, the customer user will be notified of the status update.

5.2. Updating Result Attachment

Invoke the same endpoint to submit the assessment package result and update the package status to COMPLETED.

Your service may add additional reports or attachment to the assessment results with the /orders/{orderId}/results/attachment endpoint below, using the POST method:

https://api.smartrecruiters.com/assessment-api/v202010/orders/{orderId}/results/attachment

SmartRecruiters allows multiple attachments to be attached to a single package or an assessment object. If your service would like to update an attachment, please ensure the attachment has the same URL. If the assessment attachment gets updated frequently, we recommend your service host a URL for the attachment and pass SmartRecruiters the hosted URL instead.

1278

Fig. 3 Resolving order and querying additional resources

Updated about 1 month ago