At Teamtailor we embrace our Tech Ecosystem because we understand it empowers our users to manage their recruitment in a modern way that makes them smile. We're excited that you are interested to integrate your HR/recruitment tool with Teamtailor.
Curious how to integrate a job board with Teamtailor, check out the support article here!
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.
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 Integrations Hub which:
allows you to edit your listing on the Teamtailor marketplace (e.g. with a pitch, logo's 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 you click on "Create a new partner":
At this stage you'll be presented with a form that you'll fill out. This will create the connection to Teamtailor that is required to be published on the marketplace. The form also contains the information that is shown in the marketplace listing.
Within the Integration's Hub you can always edit your listing by clicking on the integration's name.
Part 1
Partner name: the name of your company / platform as it should be shown on the Teamtailor marketplace.
Partner Base URL: your url where Teamtailor can fetch the webhook config from the BASE_URL/config endpoint, and post the webhook to BASE_URL/webhook. The webhook config is shown to users when they are adding the integration as a trigger in the Teamtailor platform.
Website: link to your website so that our clients can visit your website if they're interested in 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: If you have a support article for how the integration works, you can put that here.
Tech contact email: the email of the responsible person the Teamtailor team can contact for any technical questions.
Support contact email: the email of the customer support team that the customer or Teamtailor can contact for support questions. This email will be shown on the marketplace.
Webhook title - verb: you can adjust the call-to-action customers will see within the list of triggers they have available in their Teamtailor platform. The CTA button is structured 'Verb + Partner name + noun'. You could for example set this to 'Create ACME assessment'. The default for the verb is 'Send'.
Webhook title - noun: the noun part of the CTA button. The default for the noun is 'webhook', or 'test' if the assessment capability is enabled.
Part 3
Category in marketplace: the type of tooling under which your integration will be listed on the marketplace.
Logo type: the logo that will be shown on the main page of the marketplace.
White logotype: the logo that will be shown on the details page of the marketplace.
Square logotype: the logo that will be shown in the trigger list in the Teamtailor platform.
Capability to make assessments: tick this option to render an assessment score/result visual on the candidate card in Teamtailor.
Allow bulk mode: allow users to use the integration trigger in bulk mode, which will send the payload without job data to your base_url.
Advanced settings
Activation form: here you can set the webhook activation config (as an alternative to using a PUT request via the API). Customers will see this form/config when they activate the integration via the Teamtailor marketplace.
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. This integration ID is for example needed to set the webhook activation config of your integration via the API.
The API key and webhook signature are under 'show details'.
Marketplace activations
In the settings of your sandbox you can also navigate to the 'marketplace activations'. The integrations you are building in the sandbox are always automatically activated for you, to allow testing. You can also click 'view settings' to see how your webhook activation config looks like here as well.
How tech partner integrations work in Teamtailor
Most integration withs Teamtailor use webhook triggers. These triggers can for example be used for integrations that transfer data from Teamtailor to your platform (sending candidates to HR systems), or to start a workflow in another tool (for example assessments, e-signing, or background checks).
Read more about triggers in this article, and explore your sandbox to get familiar with triggers.
When customers activate an integration via the marketplace in the Teamtailor app they will be prompted to complete the 'webhook activation config'.
When the installation of the integration is completed the integration shows up in the 'Marketplace activations' section of the settings. Customers can also find the activation config for the integration is this section.
The integration will then also be available in the list with triggers on a job. The Teamtailor platform allows users to connect triggers to the stages of jobs, or to trigger integrations manually via the candidate card. During the set up of the trigger the user will be prompted to complete the 'webhook config'. This config is fetched by sending a request to base_url/config.
When the integration is triggered a payload with candidate data will be automatically sent to the base_url/webhook endpoint. This action automatically creates a 'partner result' on the candidate card to show the status of the trigger (e.g. Sent, Pending, Completed, Failed).
The parter-result object in Teamtailor can then be used to send back scores/results/attachments/urls onto the candidate card. Please note that you update the result, not create a new result.
Curious to see some examples? Watch our videos! 📺 💡
Curious to see some examples? Watch our videos! 📺 💡
Assessments
HR systems
Reference checks
E-signing tools
Start building
Besides the core code of your integration there are three essential steps in setting up the connection with the Teamtailor platform.
As described previously, you start by creating the partner integration in the Integration's Hub. For this you also need to create the base_url/webhook endpoint where we will send the webhook.
Create a webhook activation config via a PUT request or by using the Integration's Hub (under advanced settings). This is the config form customers will see when they activate the integration via the marketplace. In this form you can for example ask for credentials, but you can also render other settings. Each customer activation comes with a 'provider key', which is by default a random UUID string but it could be the credentials to authenticate customers against your API. We are sending this key in the Authorization header.
Create a webhook config that Teamtailor can fetch via the base_url/config endpoint. This is the config customers will see when adding the integration as a trigger to a stage, or when they manually trigger the integration.
Note 1: when Teamtailor fetches the webhook config from your server, the call will include a user-id. By combining the Partner API with our Public API you can find the exact user that is looking at the webhook config. This would allow you to show a personalized webhook config, for example if different user roles within your platform should have access to a different set of options for the trigger in Teamtailor.
Note 2: The Teamtailor Partner API allows you to query which companies have activated the integration in their Teamtailor platform. This can be done via the Partner Activation endpoint. Note that not all companies might be actively using the integration at time of the query.
Have a look at our technical documentation to read more.
For building the integration please feel free to use our starting point code:
Testing the tech partner integration
The integrations you develop will be automatically activated in your sandbox, allowing you test the full functionality of the integration.
While you are testing make sure to also create support documents to help our common customers and our support team to understand how your integration works. The support documents are also a requirement to launch your integration to the Teamtailor marketplace. You can find more information about the requirements for the article in this guide.
Launching your integration to Teamtailor 🚀
Once you've completed the development and testing you can take the last steps to launch your integration to the Teamtailor marketplace. For this last step please follow the steps in this guide.
What support will I get after the integration is live?
If you or your customers experience issues with the integration you can always reach out to the Teamtailor Support Team, either via the chat in your (sandbox) platform or via support@teamtailor.com.