Create Application Questions
Applicant Profile Data
By default, all candidates applying to a Talroo Apply job will be asked for the following profile building information:
- Name
- Phone
- Location - Zipcode, City, and State
- Resume
- Whether or not resume is required can be set with the
<resume_required>node within the XML Job Feed (see below)
- Whether or not resume is required can be set with the
Applicant Resume
The Talroo Apply system allows advertisers to control whether their applications require applicants provide a resume. Given the large presence of mobile based job seekers in today’s environment, by default, Talroo will not require resumes from Talroo Apply applicants.
To indicate whether a resume is required for a job’s application, you can use the <resume_required> node within the <talroo_apply> node:
- To require a resume for the application, you can pass a value of
trueor1in the<resume_required>node - To NOT require a resume for the application, you can pass a value of
falseor0in the<resume_required>node - You can also work with your Talroo POC to set a fallback value of
true, orfalseto use if the<resume_required>node is omitted from the XML feed
Example for Resume Required
<talroo_apply>
<custom_questions><![CDATA[https://example.com/custom_questions.json]]></custom_questions>
<postUrl><![CDATA[https://example.com/postUrl]]></postUrl>
<addressCollection><![CDATA[required]]></addressCollection>
<resume_required><![CDATA[true]]></resume_required>
</talroo_apply>
Example for Resume Optional
<talroo_apply>
<custom_questions><![CDATA[https://example.com/custom_questions.json]]></custom_questions>
<postUrl><![CDATA[https://example.com/postUrl]]></postUrl>
<addressCollection><![CDATA[required]]></addressCollection>
<resume_required><![CDATA[false]]></resume_required>
</talroo_apply>
Applicant Address
The Talroo Apply system allows advertisers to control whether their applications require applicants provide their address.
To indicate whether an address is required for a job’s application, you can use the <addressCollection> node within the <talroo_apply> node:
- To require an address for the application, you can pass a value of
requiredin the<addressCollection>node - To allow an address be provided, but not require one for the application, you can pass a value of
optionalin the<addressCollection>node - To hide the address question for the application, you can pass a value of
offin the<addressCollection>node - Values options are case insensitive
- You can also work with your Talroo POC to set a fallback value of
required,optional, oroffto use if the<addressCollection>node is omitted from the XML feed
Example for Address Required
<talroo_apply>
<custom_questions><![CDATA[https://example.com/custom_questions.json]]></custom_questions>
<postUrl><![CDATA[https://example.com/postUrl]]></postUrl>
<addressCollection><![CDATA[required]]></addressCollection>
<resume_required><![CDATA[false]]></resume_required>
</talroo_apply>
Example for Address Optional
<talroo_apply>
<custom_questions><![CDATA[https://example.com/custom_questions.json]]></custom_questions>
<postUrl><![CDATA[https://example.com/postUrl]]></postUrl>
<addressCollection><![CDATA[optional]]></addressCollection>
<resume_required><![CDATA[false]]></resume_required>
</talroo_apply>
Example for Address Hidden
<talroo_apply>
<custom_questions><![CDATA[https://example.com/custom_questions.json]]></custom_questions>
<postUrl><![CDATA[https://example.com/postUrl]]></postUrl>
<addressCollection><![CDATA[off]]></addressCollection>
<resume_required><![CDATA[false]]></resume_required>
</talroo_apply>
Application Questions
In addition to the profile building data listed above, customers who utilize the Talroo Apply Frame work can ask additional Application questions to better evaluate their applicants and more quickly determine whether they are a good fit for the role.
To utilize Application Questions in the Talroo Apply application flow, format them in JSON and provide them in each <job> under the <talroo_apply> parent node using one of the following:
<custom_questions>— HTTPS URL that returns the Application Questions JSON<custom_question_json>— the Application Questions JSON itself, inline in the feed (CDATA-wrapped)
Do not include both <custom_questions> and <custom_question_json> on the same job.
If you use <custom_questions>, the URL must respond with Application Questions JSON within 4 seconds or else the job will be invalidated.
See the Job Feed Specification page for examples of the <talroo_apply> nodes.
Considerations
- Talroo supports Qualifying Questions, questions that require a correct answer or selection in order for the application to be considered qualified
- Applications that are disqualified will not be used for optimization efforts by our system. Additionally, you can chose to have disqualified applications not sent to your system.
- You can ask up to 100 questions on a single application, however, it is highly recommended to keep the Application question count to 25 and under in order to preserve conversion rates
- Data shows most job seekers do not have their resume on their mobile device – Given the large amount of mobile traffic within Talroo’s ecosystem, it is recommended to use the
<resume_required>node to make resumes optional when applicable - Talroo does not allow Application Questions to unnecessarily request personally identifiable information (PII) from job seekers
Application Questions JSON
Application questions should only include those not already asked as part of the profile building questions. Do not reuse profile field ids such as first_name, firstName, last_name, lastName, email, phone, profile_phone, city, profile_city, state, profile_state, zip, zipcode, postal_code, profile_postCode, resume, address, tal_extra_address, or contact_form_title.
Below is a table outlining the individual Application Question parameters
| Name | Required? | Description | Values | Example |
|---|---|---|---|---|
id | Yes | Unique ID for this question (max 256 characters). | String | “drivers_license” |
type | Yes | Question type | "textarea", "text", "select", "hierarchical", "multiselect", "date", "file", "information", "pagebreak", "questionset" | “select” |
question | Yes | Question text shown to the applicant. Supports the same HTML tags as text. Not required for "information" type. On a pagebreak, this is the optional page title. | Any string | “Do you have a driver’s license?” |
text | No | HTML-supported copy shown to the applicant. Required for "information" question type. Allowed tags: <a>, <b>, <strong>, <i>, <em>, <u>, <p>, <br>, <li>, <ul>, <ol> | Any string | “The following questions are optional” |
options | No | List of choices. Required for "select", "multiselect", and "hierarchical" type questions. Each item needs a unique string value (what Talroo returns) and a label (what the applicant sees). On select/multiselect, an option may also include correct: true — see Qualifying Questions. | JSON | [{"value": "1", "label": "Yes", "correct": true}, {"value": "0", "label": "No"}] |
hierarchicalOptions | No | Follow-up questions revealed by a hierarchical answer. Required for "hierarchical" type questions. | JSON | See the "hierarchical" example below |
correct | No | Qualifying range on an integer or decimal text question, e.g. "[2,40]". For select/multiselect, put correct on the option instead — see Qualifying Questions. | "[min,max]" | "[2,40]" |
required | No | If set to true, the question is required, which produces a non-empty text field or selection. Omit this parameter to define questions as optional. If the applicant does not answer, the question is usually omitted from the application data. Required if the question uses correct | true | true |
format | No | The accepted format of the input. If used with a "text" type question, the value of this field only accepts "integer", "decimal", "numeric_text". See text question type below for more. | “integer”, “decimal”, “numeric_text” | integer |
limit | No | For "text" and "textarea" type questions, the character limit for the answer. For "questionset" type questions, the maximum number of copies the applicant can add (defaults to 5 when repeated is true, 1 when false). | Positive integer | 100 |
min | No | For "integer" or "decimal" format questions, the minimum value for the answer. For "date" type questions, the date that the answer must be on or after. | See text and date | "0", "1970-01-01" |
max | No | For "integer" or "decimal" format questions, the maximum value for the answer. For "date" type questions, the date that the answer must be on or before. | See text and date | "80", "2100-01-01" |
condition | No | Show this question only when an earlier question has a given answer. See Conditional questions. | JSON | {"id": "parent1", "value": "0"} |
questions | No | The list of questions shown inside a question set. Required for "questionset" type questions and must be non-empty. May contain any question type except "hierarchical", "pagebreak", or another "questionset". | JSON | See the "questionset" example below |
repeated | No | For "questionset" type questions, set to true to let applicants add more than one copy of the set. Set to false for a single copy. | true | true |
Question Types
textarea
A question that displays a multi-line text entry field. Used for questions with long-form answers.
Optional fields:
requiredlimit: character limit for the answer (positive integer)condition: see Conditional questions
Example
{
"id": "work_environment",
"question": "Describe your ideal work environment:",
"type": "textarea",
"limit": 500
}
text
A question that displays a single-line text entry field. Used for questions with shorter answers. The following format specifications are supported:
- No format
- Integer: Displays whole numbers
- Numeric text: Allows for numbers with leading zeroes; does not allow for decimals; does not allow negative numbers
- Decimal: Displays numbers with decimals; allows for leading zeroes.
Optional fields:
requiredformat:"integer","decimal", or"numeric_text"min/max: allowed range when format is integer or decimal. Must be strings ("0","80"), not JSON numbers. Integer values may only contain digits ("-1"is not valid). Decimal may include a leading minus ("-1.5").correct: qualifying range for integer or decimal — see Qualifying Questionslimit: character limit for the answer (positive integer)condition: see Conditional questions
Example (decimal format)
{
"id": "gpa",
"question": "What was your GPA?",
"type": "text",
"format": "decimal"
}
select
Allows applicants to select a single answer from a dropdown menu of answers.
Provide at least one option. Each option value must be a unique string, not a number.
Optional fields:
required. Required if any option hascorrect: trueoptions(required): each item needsvalueandlabel. An option may includecorrect: true— see Qualifying Questionscondition: see Conditional questions
Example
{
"id": "work_eligibility",
"question": "Are you eligible to work in the United States?",
"type": "select",
"required": true,
"options": [
{
"label": "No",
"value": "no"
},
{
"label": "Yes",
"value": "yes",
"correct": true
},
{
"label": "Yes, with sponsorship",
"value": "sponsorship",
"correct": true
}
]
}
multiselect
Allows applicants to select multiple answers from a list of answers.
Provide at least one option. Each option value must be a unique string, not a number.
Optional fields:
required. Required if any option hascorrect: trueoptions(required): each item needsvalueandlabel. An option may includecorrect: true— see Qualifying Questionscondition: see Conditional questions
Example
{
"id": "availability",
"question": "Please select all shifts you are available to work:",
"type": "multiselect",
"options": [
{
"label": "Morning",
"value": "0"
},
{
"label": "Afternoon",
"value": "1"
},
{
"label": "Evening",
"value": "2"
},
{
"label": "Night",
"value": "3"
}
]
}
Hierarchical
Show additional questions and question choices based on previously selected answers. Useful for defining answer choices for subsequent questions based on an applicant's answer.
Nesting is limited to two levels. Child types may be text, textarea, select, multiselect, date, file, or information (omitting type defaults to select). Only select and multiselect children can reveal a further child.
Fields:
requiredoptions(required): the parent choices. Each item needsvalueandlabelhierarchicalOptions(required): the follow-up questions. Each child uses the same fields as a top-level question of that type — includingformat,min,max,required,limit, and qualifyingcorrect. Non-select children must have aquestion(exceptinformation, which usestext) and must not includeoptionscondition: see Conditional questions
Example
{
"id": "has_rn_license",
"question": "Do you have a Registered Nurse license?",
"required": true,
"type": "hierarchical",
"options": [
{
"label": "No",
"value": "0"
},
{
"label": "Yes",
"value": "1"
}
],
"hierarchicalOptions": [
{
"condition": {
"id": "has_rn_license",
"value": "0"
},
"id": "nursing_school",
"question": "Are you currently attending nursing school?",
"options": [
{
"label": "No",
"value": "0"
},
{
"label": "Yes",
"value": "1"
}
]
},
{
"condition": {
"id": "nursing_school",
"value": "1"
},
"id": "nursing_school_graduation",
"question": "When are you expected to graduate?",
"required": true,
"options": [
{
"label": "Within the next six months",
"value": "0"
},
{
"label": "Within the next year",
"value": "1"
},
{
"label": "More than a year from now",
"value": "2"
}
]
},
{
"condition": {
"id": "has_rn_license",
"value": "1"
},
"id": "rn_license_time",
"question": "Have you had your RN license for more than six months?",
"options": [
{
"label": "No",
"value": "no"
},
{
"label": "Yes",
"value": "yes"
}
]
}
]
}
Example (follow-up that is not another dropdown)
{
"id": "has_certification",
"question": "Do you have a forklift certification?",
"required": true,
"type": "hierarchical",
"options": [
{ "label": "No", "value": "0" },
{ "label": "Yes", "value": "1" }
],
"hierarchicalOptions": [
{
"id": "certification_date",
"type": "date",
"question": "When did you receive it?",
"required": true,
"condition": {
"id": "has_certification",
"value": "1"
}
}
]
}
date
A question used to take a date answer.
Applicants enter MM/dd/yyyy.
Data is returned as yyyy-MM-dd.
Optional fields:
requiredmin/max: the date must be on or afterminand on or beforemax. Eitheryyyy-MM-ddorMM/dd/yyyycondition: see Conditional questions
Example
{
"id": "start_date_one",
"question": "Start date",
"required": true,
"type": "date"
}
file
Allows applicants to submit files via a file upload interface. This can be used for certifications, cover letters, portfolios etc.
Optional fields:
requiredcondition: see Conditional questions
We only support up to two file type questions.
Supported file types: .docx, .doc, .pdf, .html, .htm, .txt, .rtf.
There is a 7mb limit on applicant submitted files.
Example
{
"id": "cover_letter",
"question": "Please attach a cover letter.",
"required": false,
"type": "file"
}
Information
Used to display informative or explanatory text. Does not collect an answer.
Fields:
text(required): the copy shown to the applicantcondition: see Conditional questions
The following HTML tags are supported in text and in question copy: <a>, <b>, <strong>, <i>, <em>, <u>, <p>, <br>, <li>, <ul>, <ol>. Other tags are stripped.
Example
{
"id": "information_question",
"text": "While it is not strictly necessary, it is highly recommended to provide a cover letter to highlight the reasons on why you would make a great candidate for this position.",
"type": "information"
}
pagebreak
Use this question type to group questions onto a single page. All questions between two pagebreaks will be shown on the same page to the applicant.
Fields:
question: on the opening pagebreak, the page title the applicant sees (for example, Work History). The closing pagebreak does not need a title.
Like other questions, ids for pagebreak type questions must be unique.
If you use pagebreaks at all, the first and last items in the JSON must be pagebreaks, they must be paired (open/close), a page's closing pagebreak must sit immediately next to the next page's opening pagebreak, and each page must contain at least one question.
While it is not required, it is highly recommended to utilize pagebreak questions to group related questions and improve the application experience.
Example
{
"id": "page1_open",
"type": "pagebreak",
"question": "Work History"
},
...
{
"id": "page1_close",
"type": "pagebreak"
}
questionset
Groups a set of questions that an applicant can fill out one or more times.
This is useful for repeatable information such as multiple work-experience entries, references, or phone numbers.
When repeated is true, the applicant sees an Add more button to add additional copies of the group (copies after the first have a number appended to the section heading, e.g. Work Experience #2) and can remove any copy once more than one has been added.
The following parameters are specific to questionset questions:
questions(required): the questions shown inside the set. Must be a non-empty array, and may contain any question type excepthierarchical,pagebreak, or anotherquestionset.repeated: set totrueto allow more than one copy of the set; set tofalsefor a single copy. (Ifrepeatedis omitted,limitdefaults to 5.)limit: the maximum number of copies the applicant can add. Defaults to5whenrepeatedistrueand1when it isfalse.required: set totrueto require at least one copy be completed.condition: optionally show or hide the entire set based on an earlier question's answer, just like other question types.
A question inside a question set may use a condition that references an earlier question — either a sibling within the same set or a question that appears before the set. However, a question outside a question set cannot reference the set, or any of the questions inside it, in a condition — because a repeated set can have more than one set of answers.
Siblings inside a question set may share the same id when each copy is shown for a different parent answer (for example, one state field per country). Those variants are mutually exclusive, so the shared id still maps to one answer field.
Avoid placing a file question inside a repeated set: each copy adds its own file upload, so a repeated set can produce more attachments than the file question limits allow.
Example
{
"id": "work_experience",
"question": "Work Experience",
"type": "questionset",
"repeated": true,
"required": false,
"limit": 5,
"questions": [
{
"id": "employer",
"question": "Employer name",
"type": "text",
"required": true
},
{
"id": "job_title",
"question": "Job title",
"type": "text",
"required": true
},
{
"id": "currently_work_here",
"question": "I currently work here",
"type": "select",
"options": [
{ "label": "Yes", "value": "yes" },
{ "label": "No", "value": "no" }
]
},
{
"id": "end_date",
"question": "End date",
"type": "date",
"condition": { "id": "currently_work_here", "value": "no" }
}
]
}
When the applicant submits, a questionset answer is returned as an array of objects — one object per copy — with each object keyed by the id of the questions inside the set and valued by that sub-question's answer (for select/multiselect sub-questions, the option value, not its label).
See Receiving Application Data for the returned shape.
Conditional questions
Add a condition to any question to show it only when an earlier answer matches.
For example, after asking if the applicant still works at a company, you can show an end-date question only when they answer no.
The trigger must appear earlier in the JSON than the question that uses condition.
A condition can key off:
- A
select,multiselect, orhierarchicalquestion —valueis that option's string (not a number) - A
text,textarea, ordatequestion —valueis the string the applicant entered - A built-in profile field that is collected before employer questions, such as
resume null— the earlier question was left unanswered (optional questions only)
A condition cannot reference a questionset or any question inside one.
Example
{
"id": "end_date_one",
"condition": {
"id": "currently_work_here",
"value": "0"
},
"question": "End date",
"required": false,
"type": "date"
}
Example (show only when an earlier optional question was left unanswered)
{
"id": "shift_details",
"condition": {
"id": "shift_preference",
"value": null
},
"question": "If you did not pick a shift, tell us why",
"type": "text"
}
Example (show only when the applicant did not upload a resume)
{
"id": "work_summary",
"condition": {
"id": "resume",
"value": null
},
"question": "Briefly describe your recent work history",
"type": "textarea"
}
Qualifying Questions
Qualifying Questions are application questions that require certain answers for the application to be considered qualified.
These answers are indicated as part of a question’s parameters, and are supported for select and multiselect questions (via correct: true on options), for text questions with "format": "integer" or "decimal" (via a correct range string), and for the same types when they appear as hierarchical follow-ups.
Applications not considered qualified will not be used for optimization efforts by our system.
By default, applications not considered qualified will not be sent you, however, you can work with your Talroo POC to override this setting at the campaign level so that we send both qualified and unqualified applications.
Qualifying Questions perform exceptionally well when paired with our Target CPA bidding strategy.
Select Example: With the following question, only applicants who indicate “Yes” or “Yes, with sponsorship”, will be considered qualified.
{
"id": "work_eligibility",
"question": "Are you eligible to work in the United States?",
"type": "select",
"required": true,
"options": [
{
"label": "No",
"value": "no"
},
{
"label": "Yes",
"value": "yes",
"correct": true
},
{
"label": "Yes, with sponsorship",
"value": "sponsorship",
"correct": true
}
]
}
Multiselect Example: With the following question, applicants who select any of the first three answers, "BLS", "ACLS", or "PALS", will be considered qualified.
{
"id": "certifications",
"question": "Please select which of the following certifications you have:",
"type": "multiselect",
"required": true,
"options": [
{
"label": "BLS",
"value": "BLS",
"correct": true
},
{
"label": "ACLS",
"value": "ACLS",
"correct": true
},
{
"label": "PALS",
"value": "PALS",
"correct": true
},
{
"label": "None of the above",
"value": "none"
}
]
}
Integer / decimal example: With the following question, only applicants who enter a value from 2 through 40 (inclusive) are considered qualified. Either bound may be omitted: "[2,]" means 2 or more; "[,40]" means 40 or fewer. Bounds may be negative. The question must be required.
{
"id": "years_experience",
"question": "How many years of experience do you have?",
"type": "text",
"format": "integer",
"required": true,
"min": "0",
"max": "50",
"correct": "[2,40]"
}
Application Question JSON Schema
Below is an example of a JSON containing all question types.
All Application Question JSONs — whether returned by a <custom_questions> URL or provided inline via <custom_question_json> — should follow this schema.
Example Question JSON
[
{
"id": "page1_open",
"type": "pagebreak",
"question": "Work History"
},
{
"id": "previous_company",
"limit": 100,
"question": "What company did you work for previously?",
"required": true,
"type": "text"
},
{
"id": "currently_work_here",
"question": "I currently work here",
"required": false,
"type": "select",
"options": [
{
"label": "No",
"value": "0"
},
{
"label": "Yes",
"value": "1"
}
]
},
{
"id": "start_date_one",
"question": "Start date",
"required": true,
"type": "date"
},
{
"id": "end_date_one",
"condition": {
"id": "currently_work_here",
"value": "0"
},
"question": "End date",
"required": false,
"type": "date"
},
{
"id": "page1_close",
"type": "pagebreak"
},
{
"id": "page2_open",
"type": "pagebreak"
},
{
"id": "school_years",
"question": "How many years of nursing school did you attend?",
"type": "text",
"format": "numeric_text"
},
{
"id": "gpa",
"question": "What was your GPA?",
"required": true,
"type": "text",
"format": "decimal"
},
{
"id": "page2_close",
"type": "pagebreak"
},
{
"id": "page3_open",
"type": "pagebreak"
},
{
"id": "has_rn_license",
"question": "Do you have a Registered Nurse license?",
"required": true,
"type": "hierarchical",
"options": [
{
"label": "No",
"value": "0"
},
{
"label": "Yes",
"value": "1"
}
],
"hierarchicalOptions": [
{
"condition": {
"id": "has_rn_license",
"value": "0"
},
"id": "nursing_school",
"question": "Are you currently attending nursing school?",
"options": [
{
"label": "No",
"value": "0"
},
{
"label": "Yes",
"value": "1"
}
]
},
{
"condition": {
"id": "nursing_school",
"value": "1"
},
"id": "nursing_school_graduation",
"question": "When are you expected to graduate?",
"required": true,
"options": [
{
"label": "Within the next six months",
"value": "0"
},
{
"label": "Within the next year",
"value": "1"
},
{
"label": "More than a year from now",
"value": "2"
}
]
},
{
"condition": {
"id": "has_rn_license",
"value": "1"
},
"id": "rn_license_time",
"question": "Have you had your RN license for more than six months?",
"options": [
{
"label": "No",
"value": "no"
},
{
"label": "Yes",
"value": "yes"
}
]
}
]
},
{
"id": "page3_close",
"type": "pagebreak"
},
{
"id": "page4_open",
"type": "pagebreak"
},
{
"id": "desired_hours",
"question": "How many hours would you like to work a week?",
"required": false,
"type": "text",
"format": "integer",
"min": "0",
"max": "80"
},
{
"id": "availability",
"question": "Please select all shifts you are available to work:",
"type": "multiselect",
"options": [
{
"label": "Morning",
"value": "0"
},
{
"label": "Afternoon",
"value": "1"
},
{
"label": "Evening",
"value": "2"
},
{
"label": "Night",
"value": "3"
}
]
},
{
"id": "work_environment",
"question": "Describe your ideal work environment:",
"type": "textarea"
},
{
"id": "page4_close",
"type": "pagebreak"
},
{
"id": "page6_open",
"type": "pagebreak"
},
{
"id": "work_eligibility",
"question": "Are you eligible to work in the United States?",
"type": "select",
"required": true,
"options": [
{
"label": "No",
"value": "no"
},
{
"label": "Yes",
"value": "yes",
"correct": true
},
{
"label": "Yes, with sponsorship",
"value": "sponsorship",
"correct": true
}
]
},
{
"id": "page6_close",
"type": "pagebreak"
},
{
"id": "page7_open",
"type": "pagebreak"
},
{
"id": "information_question",
"text": "While it is not strictly necessary, it is highly recommended to provide a cover letter details and highlight into highlight the reasons on why you would make a great candidate for this position.",
"type": "information"
},
{
"id": "recent_example_work",
"question": "Please attach a cover letter.",
"required": false,
"type": "file"
},
{
"id": "page7_close",
"type": "pagebreak"
},
{
"id": "page8_open",
"type": "pagebreak"
},
{
"id": "work_experience",
"question": "Work Experience",
"type": "questionset",
"repeated": true,
"required": false,
"limit": 5,
"questions": [
{
"id": "employer",
"question": "Employer name",
"type": "text",
"required": true
},
{
"id": "job_title",
"question": "Job title",
"type": "text",
"required": true
}
]
},
{
"id": "page8_close",
"type": "pagebreak"
}
]