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 which are not. These relations are critical to understand how Teamtailor works.
Letās take, for example, the Job Application model in our API documentation. As you can see, it has Attributes and Relations.
Letās take, for example, the Job Application model in our API documentation. As you can see, it has Attributes and Relations.
Attributes contain data that is unique to this specific Job Application - when its created if its sourced and so on.
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 itself 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 contains 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 setup. 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 with 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, 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 be and a helpful library which 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 are 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 cooldown 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 afterwards.
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 on 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 was 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 that can help with that.