Requesting Candidate Reply Data
- Where can I get the candidate reply data?
For each client, we provide a unique API URL that allows you to retrieve the XML feed containing candidate replies from their Teamio account for the requested time range. For more details, see the API request configuration section of this document. - Are all candidate replies which company received available through this API?
The API includes only direct replies from the job ad application form. Only replies received after the API was activated for the company’s Teamio account are available through it; previous replies were not exported. Candidates added to Teamio manually or from inbox are not considered direct replies and are not available through the API. See Key principles of candidate export for more details. - Can our system request all available candidate replies from the API at once?
This API can return a maximum of 200 replies per response. If the total number of candidate replies available exceeds this limit, you will receive an alert response indicating that you must narrow the time range for your request. For more details, see “Too many items” in the API Responses for unsuccessful requests section. - How can we specify which candidate replies we want to receive from the API?
You can pre-filter the results you want to receive from the API only by time range, using the parameters from, until, or alternatively fromTime and untilTime in the API URL. See the Time Range Specification section for details. Other filtering options for the request are not available (e.g., getting replies for a specific vacancy). This means the API will always return all candidate replies within the specified time period, and you’ll need to apply additional filtering of the received data on your side if you want to extract only those matching specific criteria. - How often can we request candidate replies through this API?
You can request candidate data from this API at any time, but no more frequently than once every 15 minutes. More frequent calls are not allowed and will result in an error response. For details, see API call frequency limit.
Identifying Vacancy and Candidate
- How can we link candidate replies with the job ad they applied to?
Each candidate reply in the export XML contains the pdjdId parameter, which is the unique Teamio ID of the vacancy the candidate applied to. You can use this ID to identify the corresponding Teamio recruitment and its job ads. For each recruitment, you can create a direct link to the Teamio page that contains links to all its job ads that were directly posted from Teamio by appending the pdjdId value to the following URL pattern:https://my.teamio.com/recruit/vd?pdjdId=12345678910 - How can our system recognise to which vacancy a candidate replied?
We can enable storing your system’s vacancy reference ID in Teamio and then include it in each exported candidate reply. This allows you to easily pair replies with vacancies in your system. Storing your system’s vacancy ID requires activating an additional field in Teamio called Client ID of vacancy. The Client ID value can be added manually in Teamio or sent with the vacancy information from your system if the client has the Vacancy Import API service active. The value saved in this field will then be included in the export XML for each candidate reply as the value of the clientID_0 parameter. If activation of the Client ID of vacancy field in Teamio is needed for your integration, the client can request it for their account at pomuzeme@teamio.com. - Is it possible to identify which subsidiary company’s job ad a candidate replied to?
Information about the subsidiary company under which the job ad was posted from the parent company’s account is not included in the candidate reply export. We assume your system already knows the subsidiary company for each vacancy, so you only need to correctly pair the candidate reply with it. For this purpose, you can store the reference ID of the vacancy from your system in the Client ID of Vacancy field in Teamio and then receive it with each candidate reply, as described in the previous answer. Alternatively, the subsidiary company can be identified based on the recruiter responsible for the vacancy, whose contact details (name, surname, and email) are available in the contactInformation element of the export XML. - How can we recognize that multiple replies are from the same candidate?
You can identify that the same candidate replied again (for the same or a different vacancy within the same company) by using the candidateID parameter. If Teamio recognizes the candidate as the same person, the candidateID will remain consistent across replies. This allows the destination system to group all replies from one candidate under a single profile based on the candidateID.
Processing Candidate Replies
- How can we recognize a CV in the export XML, and will it be available for every reply?
Attachments added to the reply as a CV will have either the description value 208700001 or 208700010. More details on how to distinguish a CV from other attachments are available in the section about the attachment list element. Unfortunately, we cannot guarantee that every candidate reply will include a CV attachment. In our standard Simple Reply Form, attaching a CV is not required, so candidates may choose not to attach one at all or might accidentally upload it in the field intended for other attachments. In the Flexi questionnaire (Teamio custom questionnaire), the CV field can be set by the user as required. However, this feature is fully supported only on Jobs.cz and Prace.cz job boards. The field will also appear as required wherever the candidate is redirected to the Teamio job application form. Required CV fields are not supported by the Práce za rohem app and the Atmoskop portal. In these cases, candidates will always use the standard Simple Reply Form, where the CV field is not required. We therefore recommend that your system accounts for limited support of required CV fields and accepts also candidate applications without a CV attachment. - Can you restrict attachment file types we would receive from this API?
On portals directly connected to Teamio (Jobs.cz, Prace.cz, Práce za rohem, or Atmoskop), as well as in the Teamio job application form for external websites, there are no restrictions on the types of files that candidates can attach, and these restrictions cannot be configured. We assume that different positions may require different types of attachments from candidates (e.g., when an employer requests a portfolio). Therefore, to keep things simple, we do not restrict file types—even unconventional formats like video files in .mp4 can be uploaded by candidates as attachments. We therefore recommend that your system accounts for the fact that any type of attachment can be received. If your system cannot accept certain attachment types, they will still be available in Teamio, where all candidate replies are backed up. - Will answers to our custom screening questions be included in the candidate reply export?
The answers to your custom questions will be included in the candidate reply export if the Flexi questionnaire (Teamio custom questionnaire) that contains them was used. In this case, answers to custom screening questions can be parsed from an automatically generated HTML attachment summarizing the submitted questionnaire. The file will be named according to the title of the corresponding questionnaire in Teamio and will have the description value 208700003 for Flexi questionnaires. - Can candidate status be updated in exported replies through Teamio or via API?
This API only provides candidate or vacancy information valid at the time of the reply, including candidate status. Data is not updated based on later changes in Teamio, as the purpose of this API is to enable immediate transfer of candidate replies after application. The transfer of candidate replies through this API is one-way, meaning no candidate actions in Teamio can be requested via API based on changes in the destination system, including updating candidate status. We assume that candidate applications will be processed solely in the destination system. <aside> Note: Based on the API configuration described above most candidate replies will have the initial status “Received replies” (description 208200001). A different status might appear if the candidate replies again for the same vacancy after their status changed in Teamio. For example, if the candidate was rejected in the meantime, the first reply remains unchanged, but the second reply would have status “Rejected” (description 208200003). </aside>
Testing & Troubleshooting
- Is testing environment for candidate reply export available?
There is no testing environment available for the candidate reply export or for the Teamio system in general. You can test the transfer of candidate replies through the API by:- Asking a recruiter to create a test vacancy in Teamio (either published or unpublished).
- Submitting test replies via the application form. Note that forms for unpublished vacancies are accessible through a direct link from Teamio, which recruiters can provide.
- Calling the API regularly and filtering the results for candidate replies to your test vacancy.
- Candidate reply did not appeared in our system, how can we check whether it is avalaible through API?
Verify if the candidate reply is available through the API by sending a request with the parameters from and until (or fromTime and untilTime) set to the time range when the reply was received in Teamio, as described in the Time range specification section. You can set the time range to the exact minute when the candidate reply arrived. The date and time of the reply can be found within the candidate history in Teamio.
Please note: The export time and reply submission time may not be exactly the same, as processing can take a moment. Therefore, you might find the reply in the XML feed in the minute following the actual time indicated by the reactionTimestamp parameter.
Personal Data Protection
- How is access to candidate data through this API secured?
The API is protected by multiple security measures:- Unique credentials – Each client’s Teamio account has a dedicated login and password for access to this API. In Teamio, each client has the option to change these credentials.
- Encrypted communication – All data transfers are secured using the HTTPS protocol.
- Account protection – Accounts are temporarily suspended after several unsuccessful login attempts, and a minimum interval between repeated requests is set to prevent brute-force attacks.
- IP whitelisting – Only specified IP addresses of the recruitment system are allowed to connect to the Candidate Replies Export API. This ensures that candidate data can only be transferred to the system authorized by the client.
- Is IP whitelisting required for access to the candidate replies through this API?
IP addresses of your system must be whitelisted for access to each client’s candidate replies export through this API. See the API activation and principles section for whitelist requierements. - How is GDPR compliance of candidate data processing and transfer handled by Teamio?
Processing candidate personal data within Teamio and providing it to external applications via the Candidate Replies Export API complies with the European General Data Protection Regulation (GDPR) as well as the Czech Personal Data Protection Act. Teamio includes candidate consent details within the GDPR element in the export XML for each reply. External systems should only process the candidate within the consent scope and duration specified in the GDPR element. For a detailed overview, see the GDPR compliance section.
Need more help?
If you didn’t find your answer here, feel free to contact our support team at: pomuzeme@teamio.com