Skip to main content

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
  • Email
  • 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)

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 true or 1 in the <resume_required> node
  • To NOT require a resume for the application, you can pass a value of false or 0 in the <resume_required> node
  • You can also work with your Talroo POC to set a fallback value of true, or false to 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 required in the <addressCollection> node
  • To allow an address be provided, but not require one for the application, you can pass a value of optional in the <addressCollection> node
  • To hide the address question for the application, you can pass a value of off in the <addressCollection> node
  • Values options are case insensitive
  • You can also work with your Talroo POC to set a fallback value of required, optional, or off to 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.

warning

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

info

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

NameRequired?DescriptionValuesExample
idYesUnique ID for this question (max 256 characters).String“drivers_license”
typeYesQuestion type"textarea", "text", "select", "hierarchical", "multiselect", "date", "file", "information", "pagebreak", "questionset"“select”
questionYesQuestion 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?”
textNoHTML-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”
optionsNoList 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"}]
hierarchicalOptionsNoFollow-up questions revealed by a hierarchical answer. Required for "hierarchical" type questions.JSONSee the "hierarchical" example below
correctNoQualifying 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]"
requiredNoIf 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 correcttruetrue
formatNoThe 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
limitNoFor "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 integer100
minNoFor "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"
maxNoFor "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"
conditionNoShow this question only when an earlier question has a given answer. See Conditional questions.JSON{"id": "parent1", "value": "0"}
questionsNoThe 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".JSONSee the "questionset" example below
repeatedNoFor "questionset" type questions, set to true to let applicants add more than one copy of the set. Set to false for a single copy.truetrue

Question Types

textarea

A question that displays a multi-line text entry field. Used for questions with long-form answers.

Optional fields:

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:

  • required
  • format: "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 Questions
  • limit: 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 has correct: true
  • options (required): each item needs value and label. An option may include correct: true — see Qualifying Questions
  • condition: 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 has correct: true
  • options (required): each item needs value and label. An option may include correct: true — see Qualifying Questions
  • condition: 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:

  • required
  • options (required): the parent choices. Each item needs value and label
  • hierarchicalOptions (required): the follow-up questions. Each child uses the same fields as a top-level question of that type — including format, min, max, required, limit, and qualifying correct. Non-select children must have a question (except information, which uses text) and must not include options
  • condition: 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:

  • required
  • min / max: the date must be on or after min and on or before max. Either yyyy-MM-dd or MM/dd/yyyy
  • condition: 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:

info

We only support up to two file type questions. Supported file types: .docx, .doc, .pdf, .html, .htm, .txt, .rtf.

info

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:

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.
warning

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.

tip

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 except hierarchical, pagebreak, or another questionset.
  • repeated: set to true to allow more than one copy of the set; set to false for a single copy. (If repeated is omitted, limit defaults to 5.)
  • limit: the maximum number of copies the applicant can add. Defaults to 5 when repeated is true and 1 when it is false.
  • required: set to true to 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.
info

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.

warning

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, or hierarchical question — value is that option's string (not a number)
  • A text, textarea, or date question — value is 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.

tip

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"
}
]