Skip to main content

New Assessment API integrations


This guide describes steps taken by all the parties in order to build and enable the New Assessment API integration in chronological order

How to trigger




  • New Assessment API integration configuration must be completed prior to the customer attempting to activate the integration (the API process will fail if the accounts are not configured on the Partner side)


  1. The user navigates to the Smartrecruiters Marketplace and chooses Partner profile-> then fills the “get Started” form. This triggers the official request and registers the tracking ticket in Smartrecruiters system.

  2. Smartrecruiters Partner Ops contacts the Partner and shares the customer’s request to connect. Partner Ops do not proceed further until Partner confirms via email that the  account is ready. 

  3. The user is being contacted by their Partner account representative directly, as the customer will need to follow internal Partner’s procedures, including the contract signing and then assignment of the appropriate Technical Consultant resource to the project.

  4. Partner sets up the customer’s account on the 3rd party platform-> then reaches out back to Smartrecruiters Partners Team to confirm the account is ready. The Partner’s representative should work directly with the customer to properly configure their external platform account- Smartrecruiters Partners Team can support the customer’s efforts only inside Smartrecruiters platform.

Steps taken by Smartrecruiters Partner Ops team


Prior to activating the app, Partner has to confirm via email that the sign-in widget has been adjusted to accept a new account+ the customer’s account on the Partner’s side is ready. The user information should be stored along with the companyID which Smartrecruiters send. 

If this step is omitted, the following error will be displayed (even if the rest is done correctly):


“Unknown company ID” error message is displayed by the partner, as Partner has full control over it. If this happens, please correct the URLs in the “Configuration” endpoint.



  1. Partner Ops team enables the appropriate module on the customer’s Smartrecruiters account (ENHANCED_INTEGRATION subscription). This results in the Partner app being displayed in the customer’s account.

  2. Partner Ops team obtains companyID context assessment offer using internal Admin tool

  3. Smartrecruiters Partners Team obtains internal PartnerID using internal New Assessment API endpoint

  4. Once both values are obtained, Partners Team consultant uses PartnerID to find the correct app, copies all of the active companyIds into the request body an internal API endpoint, and simply adds the new companyID. This adds an account to the Partner app.


Smartrecruiters are using all the companyIDs in 1 request, as the endpoint overwrites the current settings.

Result: this app is now active for 2 accounts in Smartrecruiters.

The above steps might be changed in the future. Whatever the change might be, it should not have any impact on Partner’s procedures.


Steps taken by Partner during setup for a new customer

This part revolves mostly around the sign-in widget. The below steps are handled entirely by Partner, Smartrecruiters Partner Ops Team does not participate in that workflow.

Workflow summary:

  • Smartrecruiters system passes the companyID context assessment offer to the partner the moment the integration is being triggered by the customer in their Smartrecruiters account UI (An Admin of company in SR going to apps & integrations section in their account, selecting given partner and clicking Connect followed by logging in, all from the level of our UI). 

At that moment Smartrecruiters passes the company id (context assessment offer) of current customer to endpoint provided by Partner in consentUrl []

Company id is passed in url via query parameter to endpoint represented by url provided with consentUrl. It is done in the browser, and entirely handled by Partner.


  • Once the partner receives it, the Partner should then assign it to the account of the user who just logged into their system in the sign-in widget (or is already logged in). This matching should take place in the background. The sole purpose of this action is to allow the partner recognition of the user.

Substeps of assigning companyID to the account of the user-> Smartrecruiters system background sends this id and requires it to be used in the url our system exposes for sending us client_id and client_secret from a partner for a customer who enabled the integration. This should be done by the partner, Smartrecruiters do not handle this part.


where “companyId” is company id which Smartrecruiters just passed to the vendor (context assessment offer). This has to be elastic so that this endpoint can take new company ID each time a new customer connects.

This request is done on the background so Partner has to use a passed company id context assessment offer, so we know which company we should match credentials returned by the partner to.

Steps taken by the end user during setup

The configuration is required from the Smartrecruiters UI level. This is the last and only step the customer has to do on the Smartrecruiters side. Before the connection is made, please make sure the user has an active account in the Partner platform and the previous steps have been completed.




  1. The Admin of the company logs into their Smartrecruiers account and navigates to Settings/ Admin-> Apps& Integrations-> selects the partner on the list-> clicks Connect-> clicks Allow and Continue-> fills in the sign-in widget provided by the partner.
  2. The user has to fill in the credentials they’ve been given by the Partner to log into their account and proceed with the sign in procedure. The app is now fully connected.

Instruction of use for the end user


Changes in the UI

The only actual change in day to day use the customer will see is another overlap added to the candidate profile, which will be used to order the assessments.


Using any integration relying on the New Assessment API requires one-time authentication (through Apps&Integrations sign-in widget)


Log into Smartrecruiters, click on the avatar-> Settings/ Admin-> Apps&Integrations


Find the desired app on the list and click on its name

The user will be asked to connect the app which requires one-time authorization and signing in via the sign-in widget. 

Click "Allow and continue"

The user is supposed to use the credentials used to log into the Partner’s platform.

The green dot next to the app in the Apps&Integrations view indicates that the app has been correctly connected.


Ordering the assessment

  • This process is triggered similarly to the standard Marketplace assessment integrations. The user finds a desired candidate and opens their profile. This time, instead of choosing the type of assessment from the section, the user clicks “PREFERRED” section and clicks browse.

  • The menu will popup, showing available assessments. In this section, the user picks the desired assessment (depending on the partner, it could be more than 1 at a time).

  • Confirmation window will pop up.

(the information about the candidate receiving an email derives from the standardized workflow, held by the vast majority of the Partners, but Smartrecruiters do not send out any messages to candidates at this step. The main point of this information is to assure the user that the next steps are expected to take place on the Partner’s side.)

  • Once the candidate completes the assessment, the results will be shown on the candidate profile. 


  • The paperclip symbol signalizes there’s an attachment available for this assessment. Clicking on it will redirect the user to the Partner’s site, displaying detailed results.