Skip to main content

Overview

StackOne allows you to integrate your Teamtailor integration app with the Assessment and Background Check categories. This guide covers how you can set up/configure integration at Teamtailor and integrate with StackOne.

Partnership Requirements

The partnership with Teamtailor Integration is necessary to proceed with this documentation.
To become a Teamtailor Integration Partner, navigate to resource partnership, then click on Apply today which will scroll down to the Integration Partner section that contains a Find out more button to direct you to the Integrate with Teamtailor page.
Integrate with Teamtailor page
Click on Apply as Tech Partner! button to fill out the Teamtailor - Tech Partner Integration Request Form.
Once you have obtained the Teamtailor partnership, follow the steps below to create an integration with Teamtailor for the Assessment & Background Check categories.

StackOne approach for Teamtailor Integration

Once you create an Integration Partner in Teamtailor, the next step is to enable and configure Teamtailor in StackOne. This process will generate an External Trigger Token for users, which acts as a key to activate/enable your integration through the Teamtailor Marketplace. Users will utilise this External Trigger Token to integrate the Assessment/Background Check partner application into their job stage workflow.
StackOne approach

Provider Side Setup

1

Navigate to Integration's hub

Log into your Teamtailor account. To access the Integration Hub, select the Settings option in the top-right corner.
navigate to settings
2

Start creating the Integration Partner

To add a new partner, click on the CREATE A NEW PARTNER button.
create a partner
3

Fill out the form to create a partner app

Complete the New Partner’s form by filling out all the required fields:
  • Partner’s Name - Enter the name of the integration partner.
  • Partner Base URL - Enter the endpoint URL provided by StackOne that will be used to fetch the input field configurations with the list of packages and to send candidate test notifications.
https://api.stackone.com/external-trigger/teamtailor
  • Category - The integration will be categorised and displayed under the chosen category, such as Assessments or Background Checks, on Teamtailor’s Marketplace.
    new partner
  • Advanced Settings - Enter the following JSON into the activation form field:
Activation Form
{
   "config":{
      "fields":[
         {
            "type":"infobox",
            "content":"<a href='https://hub.stackone.com/integration-configuration-concepts/ats/teamtailor-assessment-or-background-check'>Click</a> here to learn how to use this integration",
            "icon":"info"
         },
         {
            "id":"externalTriggerToken",
            "type":"password",
            "label":"External Trigger Token",
            "required":true,
            "description":"The token to be used to trigger the workflow externally"
         }
      ]
   }
}
This External Trigger Token field will be visible to the user when enabling the integration from the Teamtailor Marketplace. After saving, the partner integration will be successfully created.

To obtain the credentials for partner integration

1

Find your Integration credentials

Next to your partner Integration’s name on the Grid, you will find the Integration ID.
Integration hub
By clicking on Show Details, you will be able to access the API Key.
Api Key

StackOne Configuration

1

Navigate to enable the Teamtailor at StackOne

Go to the ATS category on the Integrations page and activate Teamtailor
To Enable Teamtailor
2

Enable and Configure Teamtailor in StackOne

Fill out the necessary fields in the Teamtailor - Configuration modal:
  • Authentication Type: Select either Public + Partner API or Partner API to integrate with Teamtailor (for Assessment/Background Check integration).
  • Public API: Access to the StackOne Unified APIs, excluding the Assessments and Background Checks Unified API and its features.
  • Partner API: Access to the Assessments and Background Checks Unified API and its features, but not other StackOne Unified APIs. This allows you to integrate your provider's partner app with StackOne.
  • Public + Partner API: Access to all StackOne Unified APIs, including the Assessments and Background Checks Unified API and its features.
  • If you select Public + Partner API, the hiring team’s data will be included in the webhook notification.
  • If you select Partner API, the hiring team’s data will not be included in the webhook notification.
  • Partner Category: Select the category that corresponds to your integration on Teamtailor’s Marketplace page. For instance, if your integration is listed under the Assessments category, please select Assessment from the dropdown menu.
  • 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:
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:Enter the endpoint into the designated field:
https://your-domain.com/<route-to-the-post-endpoint>
  • Partner Integration ID: You can find the Integration ID next to the Integration Name under Settings > Integrations Hub in Teamtailor.
  • Partner Integration API Key: The API key can be found in the Integration details under Settings > Integrations Hub in Teamtailor.
To get Partner Integration ID & API Key, check this
  • Package ID - If you do not have the Package’s 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.
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 Teamtailor.
Dynamic Package ID

When you have a Static Package ID
A static package ID will be available to select in Teamtailor.
Static Package ID
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.
Teamtailor Configuration Model
Click on the Confirm or Save Changes button to enable your Partner APIs, allowing end-users to link their accounts through the Hub.
3

Add a Webhook

Navigate to the Webhooks page, click on Add webhook and 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 enable events.
Add Webhook form
Enable webhook events from the Events tab for Assessment & Background Check, such as Assessments Order & Background Check Order.
Select webhook events

ATS User Enablement

Navigate to the Accounts page or the StackOne Connector Hub to link your Teamtailor account with StackOne.
Link Teamtailor account
Users will get the External Trigger Token that is required to enable the integration from the Teamtailor Marketplace.
Teamtailor User view of External-trigger
You can refer to the Connection Guide for instructions on how to enable the Teamtailor integration from the Marketplace.

ATS User Experience

Send the test to the Candidate from Teamtailor

Test your integration with StackOne using your Teamtailor Sandbox

Follow the Teamtailor Assessment or Background Check guide regarding how to send the test from Teamtailor.

User will see after test has been sent

When a user sends an assessment or background check to a candidate, they will see a success message in the candidate application pop-up.
Teamtailor sent test view

ATS User Experience Customisation

1

To Update the result via unified api

Utilise the following endpoints to update the results:Utilise the following endpoint to get metadata to update the result of the assessment or background check:
  • Connector Meta Information with the provider key teamtailor for model assessments/results.update or background_checks/results.update

Users sees the updated results with different conditions of the assessment/background check in Teamtailor

When the result status completed without any other details
Update result with result status completed only
When the result status failed without any other details
Update result with result status failed only
When the result completed with all data except Score
completed without score
When the result failed with all data except Score
failed without score
When the result completed with all details
completed without score
When the result failed with all details
failed without score
When the result not included Result URL
without result URL
When the result not included Attachments URL
without attachments URL
When the result included multiple Attachments URL
multiple attachments URL

Testing Checklist

Provider Setup:
  • Logged-in with Admin account.
  • Valid StackOne URL.
  • Integration partner app is published to the Teamtailor’s marketplace under your selected category.
  • Teamtailor’s marketplace activation form of your integration app having an input field to enter External Trigger Token.
StackOne Configuration:
  • Selected Public + Partner API or Partner API as Authentication Type.
  • Package’s List Endpoint URL is correct.
  • Enable Teamtailor in StackOne Configuration model with the List Packages endpoint.
  • Package’s List Endpoint response is expected according to the following endpoint’s response:
ATS User Activation:
  • Enter External Trigger Token to the marketplace app to enable the integration partner app.
  • Once the app is enabled from the marketplace, the app should be visible in the Integration list under the Candidate’s application; navigate to More (the three-dot menu).
Create a Webhook:
  • Added a webhook for Teamtailor and enabled it with the events such as: Assessment Order or Background Check Order
  • Valid webhook URL to receive assessment/background check notifications.
ATS User Experience:
  • The integration app is visible in the Integration list under the candidate’s application; navigate to More (the three-dot menu).
  • A list of packages is visible in the dropdown field on the prompt when you click the integration from the list.
  • Select a package and send the webhook. A green check will appear if the notification has been sent, or an error will appear if not.
Update Result:
  • Success response from the update result endpoint.
  • Updated result details to Teamtailor’s UI.

Troubleshooting

SymptomLikely causeFix
Unable to add new Integration partner app. Teamtailor Partnership is not active.

Logged-in account is not an Admin account.
Contact Teamtailor support for partnership status.

Log in with an Admin account.
Integration partner app not visible in Teamtailor Marketplace.Partnership app might be published but not approvedContact Teamtailor support for partnership status.
Getting Failed to fetch config from partner: Unable to fetch the partner config error on the pop-up. Package’s List Endpoint URL or Static Package ID is missing from StackOne Configuration.

Invalid response getting from the Package’s List Endpoint URL.

Invalid Package’s List Endpoint URL.
Add Static Package ID if you don’t have Package’s List Endpoint URL.

Response format should be expected as mentioned in the StackOne Configuration.

Check Package’s List Endpoint URL implementation at your end.

Verify CORS.
External Trigger Token field is not visible at StackOne Connector Hub. Selected Authentication Type is incorrect.Select Authentication Type Public + Partner API or Partner API instead.
User unable to activate integration app.Invalid External Trigger Token.Ensure to copy & add valid External Trigger Token
Test notification is not received. Invalid webhook URL.

Incorrect webhook events are enabled.
Verify webhook URL.

Enable expected events as mentioned in the StackOne Configuration.
Test notification not included the job’s hiring team.Different Authentication Type instead of Public + Partner API.Select Authentication Type Public + Partner API instead.
Unable to update result.Invalid payload format.Check Connector Meta API endpoint for payload format.
Result URL or Attachment’s URL showing error when opened.Added result URL can be expired or is private.Ensure to add public or signed URLs; verify CORS and expiry.
For persistent issues, contact StackOne support with detailed error logs and configuration information.