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
When customers activate an integration via the marketplace in the Teamtailor app it shows up in their Marketplace activations section of the settings, and in the list with available triggers on a job (if webhooks are activated). The Teamtailor platform allows users to connect triggers to the stages of jobs. When a candidate is moved to that stage a partner event will be automatically sent to the base_url/webhook endpoint. User can also trigger an integration manually via the candidate card in Teamtailor.
Read more about triggers in this article, and explore your sandbox to get familiar with triggers.
Triggers can for example be used for integrations that transfer data from TT to your platform (sending candidates to HR systems), or to start a workflow in another tool (for example assessments, e-signing, or background checks).
Partner result
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
Start building
Besides the core code of your integration there are four essential steps to complete for 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.
Please note that during the development process your server can be hosted anywhere, even at your localhost.
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.