Integration Workflow

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 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 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 Principle of Least Privilege

When your requested access scope is approved, SmartRecruiters will also provide you a set of Partner Level credential (master credential) 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 of the of a pair of master credential looks like:

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

1.3 Configure URLs and Endpoints

In the early beta of this assessment API, 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://www.smartrecruiters.com/identity/oauth/token

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

curl --request POST \
  --url 'https://www.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 for the access token, you can access the configuration endpoint. The /partner/configuration endpoint accepts PUT method and expect the following payload:

{
  "consentUrl": "string",
 "consentDisplayMode": "REDIRECT",
 "assessmentPackageListUrl": "string",
 "singleAssessmentPackageUrl": "string",
 "packageOrderUrl": "string",
 "inlineAssessmentPackageOrderUrl": "string",
 "oauthTokenUrl": "string",
 "integrationDisableUrl": "string"
}
  • consentUrl: The URL which SmartRecruiters will call as the /integration endpoint which directs the customer user to for him/her to authenticate his/her identity for your service.
  • consentDisplayMode: The field which 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 in consentUrl
    • 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 as the /packages endpoint to retrieve a list of assessment packages
  • singleAssessmentPackageUrl: An endpoint defined by your service which SmartRecruiters service will call as the /packages/{asssemntPackageId} 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 SmartRecruiters will call when to exchange the credential we received from your service for access token to your endpoints..
  • integrationDisableUrl: An endpoint which your service specified to receive notifications on disabled integration for a specific customer. 

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"
}

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"
}

When SmartRecruiters service calls the consentURL, companyId, a unique identifier for customers in SmartRecruiters, also gets passed to your service. 

If your consentDisplayMode value is REDIRECT, a redirect parameter, which your service can use to redirect users back to SmartRecruiters after the authorization step is completed, is also added when SmartRecruiters service calls the consentUrl

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 SmartRecruiters 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. A sample of the your customer level credential should look like:

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

Note: Not to be confused with the master credentials on the above section, this set of credentials is for SmartRecruiters to access the customer’s data on your service.

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 /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 client id-secret pair. A sample of the of a pair looks like:

"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 front end transition by sending users back to SmartRecruiters using the url provided to you in the redirect parameter in early step.
  2. POPUP: If you choose the pop-up widget approach, SmartRecruiters will handle the front end 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.

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 are also passed along as query parameters.

The following response is expected be returned by your service:

[
 {
   "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 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

Note: For packages type = INLINE_ASSESSMENT, these packages 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",
   "language": "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. 

If the customer user configured to trigger your service during the hiring step of 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",
   "language": "string"
 },
 "assessmentPackageId": "string",
 "jobId": "string",
 "companyId": "string",
 "completedAssessmentCallbackUrl": "string"
}

When your service received the order, SmartRecruiters expects the following response:

{
 "url": "string"
}

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

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://www.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 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 packages status, submit the status change to the resultCallbackURL from the response SmartRecruiters provided you from 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.

Fig. 3 Resolving order and querying additional resources