SmartRecruiters Assessment or Background Check Integration

​

Purpose & Scope

​

Partnership Requirements

​

SmartRecruiters Marketplace Partnership

• Partnership Required: Yes, formal partnership application required
• Marketplace Application: SmartRecruiters Marketplace
• Plan Requirements: Partnership approval required regardless of SmartRecruiters plan tier
• Support Contact: Available through marketplace partner portal after approval

​

Application Process

​

Provider Side Setup

​

SmartRecruiters Configuration

​

SmartRecruiters API Documentation

• SmartRecruiters Developer Documentation
• SmartRecruiters API Reference

​

StackOne Configuration

​

Enable SmartRecruiters in StackOne Dashboard

1

Navigate to Integrations

1. Log into your StackOne Dashboard
2. Navigate to the ATS category on the Integrations page
3. Find and enable SmartRecruiters

2

Complete Configuration Form

Fill in the SmartRecruiters Configuration form with the following details:

• Authentication Type: Select OAuth2 - Assessments/Background checks for standard integration
• Partner Category: Select Assessment or Background Check based on your integration type
• Partner Client ID: Enter your SmartRecruiters Client ID from Partner Portal
• Partner Client Secret: Enter your SmartRecruiters Client Secret from Partner Portal
• Package’s List Endpoint URL: Implement and provide an endpoint to StackOne that StackOne will use to retrieve the list of packages when the recruiter wants to send a test to a candidate.

Implement the following POST endpoint:

Copy

Ask AI

curl --location 'https://your-domain.com/<route-to-the-post-endpoint>' \
--header 'Content-Type: application/json' \
--header 'x-stackone-signature: string' \
--header 'Authorization: Basic <base64-encoded-api-key>' \
--data '{
    "job_id": "49201091",
    "account_id": "456551489512493412",
    "provider": "teamtailor"
}'

The expected response of the POST endpoint (list of packages). Refer to:

• List Assessments Packages
• List Background Check Packages

Enter the endpoint into the designated field:

Copy

Ask AI

https://your-domain.com/<route-to-the-post-endpoint>

• Package ID: If you do not have the Package List Endpoint URL, you can specify a particular package ID that will be visible to the recruiter when they wish to send the test to the candidate

How is the Package's List Endpoint URL different from a Static Package ID?

The Package's List Endpoint URL allows StackOne to fetch a list of available packages from your system, while the Static Package ID is fixed and available for users to select on the provider's side.

When you have a Package's List Endpoint URL
A list of packages will be available to select in SmartRecruiters.

When you have a Static Package ID
A static package ID will be available to select in SmartRecruiters.

At least one field is necessary for making packages available in the Provider's UI. Preference will be given to the Package's List Endpoint URL, even if both fields are configured.

• SmartRecruiters Supported Assessment Types: Please select one of the assessment types supported by SmartRecruiters

3

Save Configuration

Click Confirm or Save Changes to enable your OAuth APIs and allow end-users to link their SmartRecruiters accounts via the StackOne Hub.

4

Enable Webhook Events

Configure webhook notifications for the following events based on your selected integration category:

• assessment.created - When a recruiter sends an assessment to a candidate
• background_check.created - When a recruiter initiates a background check

1

Add a Webhook

Navigate to the Webhooks page, click on Add webhook.

Fill out the form:

• Name: Enter your webhook with a recognisable name
• URL: Enter the URL where the webhook will send the notification of the enabled events

2

Configure Event

Enable webhook events from the Events tab for Assessment & Background Check, such as Assessments Order & Background Check Order

3

Save Configuration

Click Save button to save your webhook config.

​

ATS User Enablement

​

User Activation Flow

1

Obtain External Trigger Token

Users get the External Trigger Token from StackOne:

1. Navigate to StackOne Connect Hub
2. Copy the external trigger token

2

Access SmartRecruiters Marketplace

Users access the SmartRecruiters Marketplace through:

1. SmartRecruiters admin dashboard → Settings → Apps and Integrations

3

Select Integration

Navigate to specific integration from the list of available integrations in SmartRecruiters account.

1. Search for your integration by name
2. Click on your integration tile to view details

4

View Details

Review the integration details and click on Connect.

5

Enable Integration

1. Review permissions
2. Click Allow and Continue button

6

Input external trigger token into form

Users will see a verification form where they need to enter their External Trigger Token received in the previous step along with their Email Address. After filling in the details, click the Submit button to verify and continue.

7

Verify Connection

Once submitted credentials are verified successfully, user will see a message on the top right corner of the screen that says: StackOne Assessments is connected.

​

ATS User Experience

​

Ad-hoc Assessments

1

Access Job Application

1. User logs into SmartRecruiters
2. Navigates to People
3. Selects a specific candidate profile

2

Initiate Assessment/Background Check

From the candidate profile:

1. Look for the assessment section

If a candidate has multiple jobs, the Assessments section won’t appear directly on their profile. To access the assessments in this case, please follow these steps to navigate to the Assessments section for that candidate.

1

Navigate to Person profile

Navigate the Person profile and click on Job for which you want to add the assessment.

2

Find Assessments Section

Once you open the Job for the candidate, you will find the Assessments section there, specific to that particular job application.

2. Click Order Assessments button

3

Select Package

In the assessment form:

1. Select Assessment Partner: Select your assessment partner
2. Select Package: Choose from available test packages
3. Click Continue: Click on continue button

If a user selects multiple packages for a candidate, the assessment partner will receive multiple assessment orders.

4

Send to Candidate

1. Review the test details and candidate information
2. Click Send button
3. Candidate receives email notification with test link and instructions

​

Auto Trigger Assessments

1

Open Settings

User opens the profile menu and selects Settings.

2

Open Hiring Process

In Settings, user clicks Hiring Process.

3

Select Hiring Process

User creates a New Hiring Process or selects Default, then clicks the Edit icon to modify it.

4

Add step

User clicks Add Step and chooses Skills Test or any other Stage on which you want to configure the Assessments.

Once the user selects the step, it will be added to the hiring process.

User can also add a Custom Stage by selecting the Add Custom button.

Enter the name of the Stage.

Once the user clicks the Add button, the step will be added to the hiring process.

5

Save Hiring Process

User clicks Save Hiring Process to persist changes.

6

Add Assessment Entry

Inside the Skills Test step, user clicks the Menu icon and selects Assessments.

7

Configure Assessment

User clicks Configure.

User selects the Assessment Partner, Assessment Type, and Assessment Package, then clicks Save.

8

Enable Auto-trigger

After saving, user returns to the Config page and enables the Auto-triggered toggle for the selected package.

9

Add Candidate

User clicks the + icon (top right) and selects Add Candidate.

User may upload files/folders or add a candidate manually (example below):

User completes the candidate form and clicks Add Candidate.

10

Move Candidate to Assessment Stage

User opens People, selects the candidate.

Clicks Convert button under the Applicant profile section.

Clicks Move Forward, and chooses Skills Test under the In Review stage

A checkmark appears on Skills Test once the assessment order is sent.

​

User experience after test has been sent and results updated

1

User Experience after the assessment has been sent

When an assessment is sent to the candidate, the user will see the assessment status in the candidate’s application profile.

2

Review Results

Recruiters can track progress:

1. Status Updates: View real-time status in candidate profile (Sent, In Progress, Completed)
2. View Attachments: Click to view detailed results within SmartRecruiters

​

ATS User Experience Customisation

1

Update the result via Unified API

Utilise the following endpoints to update the results:

• Assessment Update Result
• Background Check Update Result

Utilise the following endpoint to get metadata to update the result of the assessment or background check:

• Connector Meta Information with the provider key smartrecruiters for model assessments/results.update or background_checks/results.update

​

Payload to UI Mapping

The following shows how different payload fields and conditions affect what users see in the SmartRecruiters UI when updating test results:

result[pending]

What users see in SmartRecruiters UI: Grey icon, Pending statusNotes: Shows test has been pending

result[in_progress]

What users see in SmartRecruiters UI: Yellow icon, In Progress statusNotes: Shows ongoing test status

result[completed]

What users see in SmartRecruiters UI: Green checkmark, Completed statusNotes: Shows successful completion status

result[failed]

What users see in SmartRecruiters UI: Red icon, Rejected statusNotes: Indicates test failure or rejection

result[expired]

What users see in SmartRecruiters UI: Yellow icon, Expired statusNotes: Shows test has expired without completion

score[value,min,max]

What users see in SmartRecruiters UI: Numerical score displayed prominentlyNotes: Value, min, and max are all required fields for score display.

score[label]

What users see in SmartRecruiters UI: Custom score label or descriptionNotes: Optional descriptive label for the score

summary

What users see in SmartRecruiters UI: Summary sectionNotes: Rich text summary of results

result_url & attachments[content_type,url]

What users see in SmartRecruiters UI: Download Reports section with file linksNotes: Both content_type and url fields are required to attach report documents. For result_url, you only need to provide the report link in the result_url field. Both types of documents will be displayed in the same section.

start_date

What users see in SmartRecruiters UI: Not currently visible in UINotes: Optional field - Assessment start timestamp (when the assessment was initiated)

submission_date

What users see in SmartRecruiters UI: Not currently visible in UINotes: Optional field - Completion timestamp (when the assessment was submitted)

​

Testing Checklist

• Partnership application approved by SmartRecruiters Marketplace.
• Integration is listed and discoverable in SmartRecruiters Marketplace.

• SmartRecruiters integration enabled in StackOne Dashboard.
• Authentication Type OAuth2 - Assessments/Background checks is selected.
• Partner Category (Assessment or Background Check) is correctly configured.
• Valid Partner Client ID and Client Secret from SmartRecruiters Partner Portal are provided.
• Package’s List Endpoint URL is implemented and returning valid response format, or Static Package ID is configured.
• SmartRecruiters Supported Assessment Types are selected.

• Webhook is created with valid URL.
• Correct webhook events are enabled (assessment.created or background_check.created).
• Webhook is receiving notifications when assessment/background check is ordered.

• External Trigger Token is successfully obtained from StackOne Connector Hub.
• StackOne account is connected successfully.
• Integration can be found and selected in SmartRecruiters Marketplace.
• Integration connection is successfully established after providing External Trigger Token and Email Address.
• Success message StackOne Assessments is connected is displayed.

• Order Assessment button is visible on candidate profile.
• Package selection dropdown displays available packages (from endpoint or static package).
• Assessment order is successfully sent to candidate.
• Assessment status updates are visible in candidate profile (Pending, In Progress, Completed, etc.).

• Inline Assessment type is selected in StackOne configuration.
• Hiring Process is configured with Skills Test step.
• Assessment is configured within Skills Test step with correct partner and package.
• Auto-triggered toggle is enabled for the assessment.
• Assessment order is automatically triggered when candidate is moved to Skills Test stage.

• Success response is received from the update result endpoint.
• Updated result status (pending, in_progress, completed, failed, expired) is visible in SmartRecruiters UI.
• Score values (value, min, max) are displayed correctly when provided.
• Summary section displays rich text summary when provided.
• Result URL and attachments are accessible in the Download Reports section.

​

Troubleshooting

​

Common Issues and Solutions