Quick Links:
- Record Types
- Question and Answers Endpoints
- Getting Questions and Answers as ResponseBlocks
- Question Types
One of the most powerful customization features Eploy gives customers is the ability to set up custom questions on various record types. This allows customers the freedom to configure custom forms to be completed by Candidates, Hiring Managers or core system users, and use these to record data specific to their organization. Custom questions are very widely used by Eploy Customers, and it is likely when building an API integration that one or more custom questions will need to be used when getting data out via the Eploy API. For some integrations, it may even be necessary to pass data back into custom questions when creating or updating record.
This guide will provide you with all the information you will need to know to work with custom questions within the Eploy API, so you know what to expect when building an integration that utilizes them.
Record Types
Custom Questions can be used on various Record Types within Eploy. The Record Type used to hold a Custom Question will depend on its intended usage. For example, if the question is to hold personal data that is specific to the Candidate, and that would not differ for each role they applied to, it would make sense for the question to be set against the Candidate record (e.g. "Emergency Contact Name"). If the question is specific to a Vacancy, and applies to all candidates who apply to that Vacancy, it would go on the Vacancy record. However, if the question is specific to each individual applicant, and relates to the role they are applying to, it may go on the Application record. If it is more specific to candidates who have been offered or who are accepting a role, it may go on the Placement record.
The full list of Record Types that custom questions may apply to are:
- Applications
- Candidates
- Companies
- Contacts
- Placements
- Vacancies
- VacancyTemplates
Question and Answers Endpoints
The Eploy API allows you to find out which questions have been set up in a system and retrieve/update the answers to the questions on various record types.
Each of the below endpoints can be used for every record type that supports custom questions. For each of the examples below, the {recordtype} can be replaced by any of the record types that support custom questions (i.e. "applications", "candidates", "companies", "contacts", "placements", "vacancies", "vacancytemplates"), and the {recordid} can be replaced with the ID of the record (i.e. the ApplicantID, CandidateID etc.)
Get all Questions for a record type
GET /api/{recordtype}/questions
e.g. to get all Candidate Questions, use GET /api/candidates/questions
Get all Questions and answers for a record
GET /api/{recordtype}/{recordid}/questions
e.g. to get all Questions and Answers for CandidateID 123, use GET /api/candidates/123/questions
Set Question Answers for a record
PATCH /api/{recordtype}/{recordid}/questions
e.g. to set Question Answers for CandidateID 123, use PATCH /api/candidates/123/questions and pass the QuestionIds and Answers you need to set, like in the example below:
[
{"QuestionId":325,"Answer":"Test"},
{"QuestionId":326,"Answer":"Test\r\nTest"},
{"QuestionId":327,"Answer":147},
{"QuestionId":328,"Answer":"Test"},
{"QuestionId":329,"Answer":148},
{"QuestionId":330,"Answer":[147,148]},
{"QuestionId":331,"Answer":"2024-05-01T00:00:00Z"},
{"QuestionId":332,"Answer":100},
{"QuestionId":333,"Answer":99.99},
{"QuestionId":334,"Answer":true},
{"QuestionId":335,"Answer":2}
]
Getting Questions and Answers as ResponseBlocks
You can get Questions and Answers as ResponseBlocks for any Search that you are doing via the API. This can save you needing to carry out multiple GET requests to obtain the data you need, because all custom question answers can be retrieved for up to 1000 records using a single API call. You can even get Questions and Answers for multiple record types in the same call. For example, if you are performing a Placement Search, you can get the answers to questions on the Placement, Candidate, Vacancy, Company and Contact.
For example:
POST /api/placements/search
{
"Paging": {
"RecordsPerPage": 1000,
"RequestedPage": 1
},
"Filters": [
{
"Route": "Placement.PlacementStatus",
"Value": 6,
"Operation": "Equals"
}
],
"ResponseBlocks":[
"PlacementID",
"Candidate",
"Vacancy",
"Candidates.Question.325",
"Companies.Question.336",
"Placements.Question.337",
"Vacancies.Question.338",
"Contacts.Question.339"
]
}
Question Types
Custom Questions can be set up using various different Question Types, which affects how the data may be input. Depending on the Question Type that is used, you can expect a different output format from the API. The table below describes all the possible Question Types, and gives examples of what you might see in an API response when requesiting the answers these type of question.
QuestionType ID: 1 |
QuestionType Description:
Input - Short Answer |
Short Answer questions are single-line text fields that allow alphanumeric and special characters to be input. | |
Screenshot | |
Example API Output |
{ |
Example API Input (PATCH) |
{"QuestionId":325,"Answer":"Test"} |
QuestionType ID: 12 | QuestionType Description:
Input - Long Answer |
Long Answer questions can contain multiple lines of test in Eploy and allow alphanumeric and special characters to be input. Note that if the answer spans multiple lines, extended notation is used to indicate this (e.g. "\r\n"). | |
Example Screenshot | |
Example API Output |
{ |
Example API Input (PATCH) |
{"QuestionId":326,"Answer":"Test\r\nTest"} |
QuestionType ID: 9 |
QuestionType Description:
Input - Drop-down |
Single-select dropdown. Must be linked to either a standard or custom OptionType (use GET /api/options/ to see all OptionTypes). In Eploy, these Question Type may either be rendered as Drop-downs or Multiple Choice (single-select radio buttons), but both are the same QuestionType in the API. Note that the API response provides the "Id", "Description" and "Reference" for the option that has been selected (also "ArchiveDate" would be populated if the option had been archived since it was answered, and "ParentId" may be populated for certain drop-down fields that have parental structure, such as Locations). |
|
Example Screenshot | |
Example API Output |
{ |
Example API Input (PATCH) |
{"QuestionId":327,"Answer":147} |
QuestionType ID: 13 | QuestionType Description:
Input - Drop-down (Text) |
Single-select dropdown, with the option to select 'Other - Please Specify' and provide a custom answer as free-text. Must be linked to either a standard or custom OptionType (use GET /api/options/ to see all OptionTypes). Note that although Dropdown (Text) questions are linked to OptionTypes in Eploy, the API response will only output the Description from the dropdown entry if an option is selected, or the custom text that has been input if the 'Other - Please Specify' was used. If you PATCH a Dropdown (Text) question, you need to pass a string. This will either be mathed against an existing dropdown option in Eploy, or specified as 'Other - Please Specify' with a custom string answer if no match is found. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":328,"Answer":"Test"} |
QuestionType ID: 10 | QuestionType Description:
Input - Checkboxes |
Checkboxes allow multiple selections to be made by ticking one or more options. Like with the "Input - Drop-down" QuestionType, for each option selected, the API response provides the "Id", "Description", "Reference" etc. Must be linked to either a standard or custom OptionType (use GET /api/options/ to see all OptionTypes). | |
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":330,"Answer":[147,148]} |
QuestionType ID: 4 |
QuestionType Description:
Input - Date |
Date fields allow the user to type or select a date from a calendar in Eploy. In the API, all Dates are returned in ISO-8601 UTC format. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":331,"Answer":"2024-05-01T00:00:00Z"} |
QuestionType ID: 2 |
QuestionType Description:
Input - Number |
Number fields allow positive or negative whole number answers to be provided. The API returns this as an integer. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":325,"Answer":"Test"} |
QuestionType ID: 21 | QuestionType Description:
Input - Decimal |
Decimal fields allow positive or negative numeric answers with up to 4 decimal places. The API returns this as an integer. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":333,"Answer":99.99} |
QuestionType ID: 3 |
QuestionType Description:
Input - Yes/No |
Yes/No fields allow a 'Yes' or 'No' answer, which is returned a boolean (true or false) in the API. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":334,"Answer":true} |
QuestionType ID: 14 | QuestionType Description:
Input - Linear Scale (1 to 5) |
Linear Scale fields allow a selection of values from 1 to 5 which are returned in the API as an integer value. |
|
Screenshot | |
Example Answer Output |
{ |
Example API Input (PATCH) |
{"QuestionId":335,"Answer":2} |