1a. Is it possible?
It is certainly possible to perform an import yourself, depending on the level of technical understanding available to the client and their patience in working through it.
This would work by having an internal resource write a script that can take information from their existing data base, transform it into a Teamtailor ready format and then send it to us. This can be done by either taking the data from the client’s existing database through API or through a document.
In the end, all that matters is that they have people capable of understanding data and APIs.
1b. Should I do it?
This is a much more difficult question - there are many pros and cons to it. Normally, this would be more advised for larger companies that have more resources to do this as well as a greater need for a quicker solution.
Pros
Can be done on your own schedule
You can decide each and every attribute and parameter that gets imported and what it should look like
It’s completely free of charge
We can offer support in explaining how this could work
Cons
Requires writing an essentially unique script that can translate information from one source to a format Teamtailor accepts
Public API has a rate limit - 50 requests per 10 seconds, which means importing a large database might take a lot of time
Requires good understanding of how data and APIs work
2. The process
Understanding Teamtailor’s data
Understanding Teamtailor’s Public API
Writing the script
Teamtailor has a relational data model, which means that objects can have attributes that are unique to them and relations to other objects that are not. These relations are critical to understanding how Teamtailor works.
Let’s take a look at the Job Application model in our API documentation as an example
Let’s take a look at the Job Application model in our API documentation as an example
As you can see, it has Attributes and Relations.
Attributes contain data unique to this specific Job Application, when it was created, if it was sourced etc.
Relations contain data that is not unique to this Job Application but exists outside of it. For example, each Job Application has a candidate and job relation.
These are used to better understand who has filled out this job application and which position it has been created for.
This is helpful since if there are changes to the Candidate or the Job, the Job Application will still be functional as it only has a link to it. It is not directly affected by the changes to the other two. However, this also means that creating certain objects within Teamtailor may require more than one request.
Candidate object
Most of the time, imports are done to import candidates and therefore it is important to understand how the candidate object works and what data can be added as attributes to the object or as relations.
As previously mentioned, a Candidate object will have a relation to a Job-Application if there has been an application previously but there are many more such relations. After all, the candidate object is the most important one in the platform.
Attributes
The most basic candidate data can be found here - most importantly it’s the name, contact information, consent data, and other such information that you might want to keep there.
However, you might notice that some other data is not found here - for example, it does not have a field for ‘gender’ or ‘age’. That is because Teamtailor operates with an open-ended data model in mind. The bare basics are here in the attributes, but additional data must be added as either Custom fields or Answers.
Relations
As you can see from this table, the Candidate may have many different relations.
Relevant to the import:
Questions and answers contain data about what questions the candidate has answered and what answers were provided. Both of these exist as individual objects outside of the candidate.
Custom-field values contain answers to all the custom fields that were previously set up. For example, if there is a custom field called ‘parent’, then the value on the candidate will say ‘yes’ or ‘no’. The custom field will be used the same, but the value will be unique to the candidate. The custom field value (yes or no) will be related to the candidate and the custom field (gender).
Notes (Comments) can contain any free-text information the recruiter has entered and can be also added through the API. This can also hold information that does not fit anywhere else, for example, a resume transcript.
Not relevant to the import:
Activities contain the information on every action that has been done on the candidate.
Uploads contain all the additional documents that the candidate has uploaded.
Partner results contain all the data we received from other integrations you may be using, for example, test results.
Department, role, regions, and locations contain different data on where the candidate is applying - these are automatically inherited from any job they have applied to and are not related to the candidate’s location directly.
2. Understanding Teamtailor’s Public API
Teamtailor’s Public API is designed in accordance with JSON:API specification. This means that we mainly use JSON when communicating through the API. The documentation has examples provided if needed and a helpful library that can be imported to your Postman as well.
Viewing the data
As explained previously, Teamtailor has a relational data model, which means a lot of the objects exist in relation to each other, including candidates and their custom field values and answers. Since only one new object can be created per request, this requires a certain amount of requests to be made for each candidate.
To make it easier, it is possible to “open” some of these relations in the response by adding an include parameter. For example, if you would like to know what the custom field values for a candidate, in the request you can add ?include=custom-field-values which will add an additional section below the data called included, which will contain all the data about the individual custom-field values that are found under that relation.
This also means that each custom-field-value, answer, or note (comment) that will be added to the candidate would need to be added as a separate request.
Rate limit
The rate limit is 50 requests per 10 seconds, so the script needs to cool down when this is reached or the requests should be spaced out so they never hit this limit. Normally adding a 300ms delay between each request is a good way to prevent reaching the rate limit.
3. Writing the script
Here is a process for a basic custom import:
Post Candidate endpoint - use this to create a brand new candidate. If there are duplicates, they will be merged by default (if the ‘merge’ attribute is set to true). This should contain the basic information for the candidate - name, email, phone number, picture, and resume.
If a resume is needed, you will first need to upload this to a public server for at least 30 seconds and then provide the URL as the resume. We will upload the resume file within those 30 seconds so you can remove them afterward.
Post Custom-field-value endpoint - use this to add custom-field values to the candidate. You will need the candidate ID and the custom field ID before you do so. Custom fields can be created through their own endpoint or added to the platform, whichever is easiest.
Post Answer endpoint - use this to add answers to the candidate card. Answers can have a relation to a job as well if the question is specific to that job. Answers are similar to custom field values, but they are meant to be something that the candidate themselves can fill out during the application, rather than something that was put in by the recruiter.
Notes (Comments) endpoint - use this if you would like to upload a lot of data and you are not fully sure how much of that data exists. This will end up on the candidate card, under the Comments tab, as a feed. Notes (Comments) require a user and a candidate.
Once the upload is complete you can validate the information found on the platform by checking the number of candidates and whether or not they have the desired data.
Support
If you run into issues like error messages or something simply doesn’t work as it should, you can contact our support by clicking on the chat box in the platform or e-mailing support@teamtailor.com
If you need help with broader questions like understanding the process better or the data structure, reach out to your Sales or CSM and they will put you in touch with someone who can help with that.