How to get started?
An official integration with Teamtailor requires a sandbox account. The sandbox gives you access to our Integration's Hub to establish a connection between platforms, and allows you to do testing with the full functionality of the platform.
To get access to a sandbox, please follow the steps in this guide. The first step is to apply for the partner program by filling out the Tech Partner integration form.
Have a look at our technical documentation to get an understanding of the integration options.
✉️ For support during development you can reach out to support@teamtailor.com
Sandbox & Integration's Hub
Once accepted to the partner program you will receive an invite to a sandbox account. In the sandbox you will find the Integration's Hub which:
Allows you to edit your listing on the Teamtailor marketplace (e.g. with a pitch, logos, and support article)
Is where you create the connection to Teamtailor
Is where you find the API key and webhook signature of your integration
Open the Integration's Hub
Log in to your Teamtailor sandbox account and navigate to the Integration's Hub by clicking on your account in the top right corner > and pick Settings.
In the settings overview you'll find the Integration's Hub in the bottom left.
Creating a new tech partner integration
To get started with your integration click on "Create a new partner".
Note 👀
To facilitate development, testing and future improvements, you can create multiple partner integrations, for example, one 'production' integration that will be launched for customers and another 'staging' integration. Please use clear naming so we can distinguish between them.
Integration details
You'll be presented with a form that creates the connection to Teamtailor and contains the information shown in your marketplace listing. You can always edit your listing by clicking on the integration's name in the Integration's Hub.
Part 1
Partner name: the name of your company / platform as it should appear on the Teamtailor marketplace.
Partner Base URL: the URL where Teamtailor can fetch the webhook config from BASE_URL/config and post the webhook to BASE_URL/webhook.
Website: a link to your website so clients can learn more about your product.
Description: a description of your product & company. Max 250 characters.
Pitch: a short pitch of your product & company. Max 150 characters.
Part 2
Support article URL: link to your integration support article if available.
Tech contact email: contact email for technical questions from the Teamtailor team.
Support contact email: the support team email shown on the marketplace.
Webhook title - verb: Enter a verb that describes the action being performed, such as "Send" or "Test". The CTA follows the format: [Verb] + [Partner Name] + [Noun]. For example, you could configure it as "Send Partner name Assessment". By default, the verb is set to "Send".
Webhook title - noun: Enter a noun that describes what is being triggered, such as "Assessment" or "Test". When the assessment capability is enabled, this field defaults to "test" but can be customized to better reflect your offering.
Part 3
Category in marketplace: the type of tooling under which your integration will be listed.
Logo type / White logotype / Square logotype: logos used in different areas of the marketplace and Teamtailor platform.
Capability to make assessments: ⚠️ This must be ticked for assessment integrations. Enabling this renders an assessment score/result visual on the candidate card in Teamtailor and makes it possible to move candidates based on their score.
Allow bulk mode: allows users to trigger the integration in bulk mode, sending the payload without job data to your base URL.
Find the integration's API key, webhook signature, and ID
Once your tech partner integration is created you can find the integration ID in the overview. The API key and webhook signature are found under "Show details".
Note 👀
The API key visible under Show Details is your personal API key and should not be used as part of the integration credentials when setting up a client.
To activate the integration for a client, you will need the Integration Key, a unique key that the client get when they activate the integration directly from their Teamtailor Marketplace.
Marketplace activations
In your sandbox settings you can also navigate to "Marketplace activations". Integrations you build in the sandbox are automatically activated for testing. You can click "View settings" to preview your webhook activation config.
How assessment integrations work in Teamtailor
Assessment integrations use webhook triggers, which start a workflow in your platform when a candidate reaches a certain stage.
When customers activate your integration via the marketplace, they complete the webhook activation config. This is typically used to collect credentials or account-level settings. This data is included in every webhook payload sent to BASE_URL/webhook.
Once installed, the integration appears in the "Marketplace activations" section of the account settings.
The integration becomes available in the trigger list on a job. Users can connect it to pipeline stages or trigger it manually from the candidate card. When a trigger is set up, Teamtailor fetches the webhook config from BASE_URL/config, this could be a dropdown of assessment packages, for example.
4. When the trigger fires, a payload with candidate data is sent to BASE_URL/webhook. This automatically creates a partner result on the candidate card showing the current status (e.g. Sent, Pending, Completed, Failed).
5. When the trigger fires, a payload with candidate data is sent to BASE_URL/webhook. This automatically creates a partner result on the candidate card showing the current status (e.g. Sent, Pending, Completed, Failed).
The partner result object is then used to push back scores, results, attachments, or URLs onto the candidate card. Note that you update the result rather than create a new one.
Note: While a partner result can contain both a Score and a Grade, the Grade will take precedence if both are provided. If you want the Score to be immediately visible, do not include a Grade.
The partner result also supports a details object, accessible via the three-dots menu → "View details". This can be used to render sub-scores or more detailed assessment output on the candidate card.
Adding extra scores with Job match score (assessment-criteria)
Assessment partners can go beyond a single overall score by pushing multiple, structured results, for example a personality test score, a communication test score, and a math test score, directly into Teamtailor's Job match score evaluation.
How it works
When you set up a trigger with one of our assessment partners, they can include detailed assessment criteria alongside the main result. If the partner has implemented this, recruiters can choose to automatically include those assessment results in the Job match score evaluation, by mapping each criterion from the partner to a Skill or Trait that is part of the job's evaluation profile.
Test results then automatically create a scorecard alongside other scorecards or interview feedback. The test results are still visible as a separate section on the candidate card, with a link to the full report in the partner's app.
Partner API: the assessment-criteria attribute
To enable this, the key attribute in the partner API is assessment-criteria. For each criterion you want to expose, you need to define:
label: the display name of the criterion (e.g. "Personality", "Communication", "Numerical Reasoning")
score: the numeric result for that criterion
The partner creates all criteria and pushes them as part of the partner result payload. Teamtailor will then surface these in the trigger configuration on the recruiter's side.
What the recruiter sees when setting up the trigger
When a recruiter activates the trigger for a job, they will see the list of criteria defined by the partner. For each criterion, they can map it to a Skill or Trait that has been created in their Teamtailor account settings.
Important: Skills and Traits must be created in advance by the recruiter under Settings → Recruitment → Interview kits before they can be used for mapping.
Once the mapping is saved, assessment results from the partner will automatically contribute to the candidate's Job match score, just like scores from interview kits.
Read more:
Job match score: how the scoring and weighting system works
How to create Skills and Traits: setting up the options recruiters can map criteria to
Testing the integration
The integrations you develop are automatically activated in your sandbox, letting you test the full functionality before launch. During this phase, customers cannot yet see your integration in the marketplace.
Make sure to also create support documentation to help customers and the Teamtailor support team understand how your integration works. This is a requirement for marketplace launch. See this guide for full requirements.
If you want to test with a beta customer, reach out to support@teamtailor.com and share the exact name of the customer's Teamtailor platform.
Launching your integration 🚀
Once development and testing are complete, follow the final steps in this guide to launch your integration to the Teamtailor marketplace.
Support after going live
If you or your customers experience issues once the integration is live, contact the Teamtailor Support Team via the chat in your sandbox platform or at support@teamtailor.com.