Screener questions

Screener Questions are a way to learn more about your job seekers during the application process. These questions should be formatted in JSON and posted to a URL so Indeed Apply can retrieve them.

Before you begin

Considerations

  • You can provide a maximum of 500 questions. However, our data indicates that a sharp drop-off in conversion occurs when more than 20 questions are asked.
  • Questions files should be no larger than 1 MB.
  • Questions files are cached server-side by unique question URLs and refreshed hourly.
  • Use the en_US locale to format limit, min, or max. Use a period for the decimal point. Do not use thousands separators.
  • The format of type=date impacts how the application is passed to the third party as well as the parsing of min and max. The job seeker still enters the date based on their locale, not the specified format, and validation error messages are in their locale’s format.
  • For type=date, use yyyy instead of yy in the format to prevent confusion.

Note: Verify the syntax of your JSON file and preview the look of your screener questions using the Indeed Apply Questions tool.

Best practices

  • Only include questions that are relevant to the job.
  • Include as few screener questions as possible. Remember that job seekers will answer these questions on mobile devices.
  • Use the “pagebreak” question type to split your application into logical sections. Indeed inserts pagebreaks by default if none are included in your JSON, but this can split your application up in unintended ways.
  • Do not repeat questions that can be answered from a job seeker’s resume, or have already been collected during the Indeed Apply application process (e.g. basic contact details).
  • Follow local laws when determining which questions to ask. Consult your legal department about questions your local laws may prohibit.
  • Provide guidance to job seekers when answers require a specific format.

JSON for screener questions

This section lists the parameters used in building all question types. For examples of specific question types, refer to Screener question types.

JSON screener question parameters

JSON screener question parameters table
Name Required? Description Allowed values Example
id Yes Unique ID for this question. any string strengths
type Yes Describes the type of question. Refer to the following sections for a full explanation of each question type. textarea

text

select

hierarchical

multiselect

date

file

information

pagebreak

textarea
question No for type=information and type=pagebreak

Yes for all other types

The question text that is displayed to applicants. any string “Veteran status?”
text Yes for type=information

No for all other types

Text that is displayed to applicants. any string “The following questions are optional.”
options Yes for type=select and type=multiselect The list of options available in the drop-down menu. JSON [{
"value":"1",
"label":"Female"
}]
value Yes for type=select and type=multiselect The value corresponding to each option that will be returned for questions with drop-down menus. any string 1
label Yes for type=select and type=multiselect The text for options in any drop-down menus. any string Female
required No Allows the setting of a question as required. When required:true is present, Indeed Apply forces a non-empty text field or a non-empty selection. When the required parameter is not present, questions are optional. If a question is optional, a possible answer value is “”. true "required":true
format Yes for type=date
No for type=text
The accepted format of the input.
Can be paired with type:text to force integer, decimal, or numeric_text validation, or with type:date to indicate how to parse date input.
Text formats:

  • integer
  • decimal
  • numeric_text
  • other locale specific formats (please use Unicode CLDR as a guide)

Date formats:

  • integer
  • dd/MM/yyyy
integer,
dd/MM/yyyy
limit No For type=text and type=textarea, the character limit for the answer. any integer 100
min No For format=integer or format=decimal, the minimum value for the answer. For type=date, the date that the answer must be on or after. any integer for format=integer

any decimal for format=decimal

any date for type=date (in the specified format)

0
max No For format=integer or format=decimal the maximum value for the answer. For type=date, the date the answer must be on or before. any integer for format=integer

any decimal for format=decimal

any date for type=date (in the specified format)

100
condition No Used to mark a question as conditional, depending on how a previous select question was answered. Specify the id of the previous question as well as the option value that activates this question.
For example, you might ask the applicant if they served in the military. If they answer yes, you display a conditional question that asks what branch they served in.
JSON "condition": {
"id": "parent1",
"value": 0}

JSON post example

The JSON post contains:

  • questions: the full questions list as described in the previous section
  • answers: the full answers list
  • url: the URL from which the questions were retrieved
  • retrievedOnMillis: the datetime in milliseconds at which the questions were retrieved

Click this link to view or download a full example JSON post file.

Screener question types

textarea

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

textarea example

{
  "id":"felonytext",
  "type":"textarea",
  "question":"If you have been convicted of a felony, please explain the circumstances around the conviction:"
}

text

A question that displays a single-line text entry field. Used for questions with shorter answers.

Note: Please see the examples below for more information on the different formats available for text questions: integer, decimal, numeric_text.

text examples

No format specification:

{
  "id": "city",
  "type": "text",
  "question": "What city are you located in?",
  "required": true
}

Integer: Displays whole numbers; does not allow for decimals or leading zeroes

{
  "id":"age",
  "type":"text",
  "question":"Age?",
  "format":"integer",
  "min":"16",
  "max":"75"
}

Numeric text: Allows for numbers with leading zeroes; does not allow for decimals

{
  "id": "ssn",
  "type": "text",
  "format": "numeric_text",
  "question": "Enter last 4 digits of your SSN.",
  "required" : false
}

Decimal: Displays numbers with decimals; allows for leading zeroes

{
  "id": "gpa",
  "type": "text",
  "format":"decimal",
  "question": "What was your GPA?",
  "required": true
}

select

A question that displays a drop-down menu that allows the applicant to select a single answer. Used for questions with multiple choice answers.

Note: If you include 5 or fewer answer options, they will display as radio buttons. If you include more than 5 options, they will display in a drop-down menu.

select example

{
  "id": "gender",
  "type": "select",
  "question": "Gender?",
  "options": [{
      "value": "0",
      "label": "Decline to answer"
    },
    {
      "value": "1",
      "label": "Male"
    },
    {
      "value": "2",
      "label": "Female"
    }
  ]
}

conditional

A question that is or is not displayed based on responses to previous questions. For example, you might ask an applicant if they are at least 18 years of age. If they answer yes, you ask if they can provide required work documentation.

conditional example

[{
    "id": "profile-atLeast18",
    "question": "Are you at least 18 years of age?",
    "required": true,
    "options": [{
        "value": "1",
        "label": "Yes"
      },
      {
        "value": "0",
        "label": "No"
      }
    ],
    "type": "select"
  },
  {
    "id": "profile-permit",
    "question": "Can you provide a work permit?",
    "required": true,
    "condition": {
      "id": "profile-atLeast18",
      "value": "0"
    },
    "options": [{
        "value": "1",
        "label": "Yes"
      },
      {
        "value": "0",
        "label": "No"
      }
    ],
    "type": "select"
  }
]

hierarchical

A question that displays additional questions and responses based on previously selected answers. For example, you might ask an applicant to choose a state. Then, depending on what they select, you could offer them a dropdown list of cities within that state. Each hierarchical question is limited to 3 levels, for example: state/city/county.

Note: Hierarchical questions are similar to conditional questions. However, hierarchical questions may be better suited to certain question types where an initial selection defines potential answers for subsequent questions. Using the hierarchical functionality reduces the total number of questions needed to obtain related information.

hierarchical example

[{
  "id": "hierarchical",
  "type": "hierarchical",
  "question": "State",
  "required": true,
  "options": [{
    "value": "0",
    "label": "California"
  }, {
    "value": "1",
    "label": "Texas"
  }, {
    "value": "2",
    "label": "New York"
  }],
  "hierarchicalOptions": [{
      "id": "cali_cities",
      "options": [{
        "value": "0",
        "label": "San Francisco"
      }, {
        "value": "1",
        "label": "Los Angeles"
      }],
      "condition": {
        "id": "hierarchical",
        "value": "0"
      }
    }, {
      "id": "texas_cities",
      "options": [{
        "value": "0",
        "label": "San Antonio"
      }, {
        "value": "1",
        "label": "Austin"
      }],
      "condition": {
        "id": "hierarchical",
        "value": "1"
      }
    },
    {
      "id": "sa_zipcodes",
      "options": [{
        "value": "0",
        "label": "78212"
      }, {
        "value": "1",
        "label": "78209"
      }],
      "condition": {
        "id": "texas_cities",
        "value": "0"
      }
    }
  ]
}]

multiselect

A question that displays a list of checkboxes that allows the applicant to select multiple answers. Used for questions with multiple answers.

multiselect example

{
  "id": "favoritecolors",
  "type": "multiselect",
  "question": "Select your two favorite colors:",
  "options": [{
      "value": "0",
      "label": "Maize"
    },
    {
      "value": "1",
      "label": "Blue"
    },
    {
      "value": "2",
      "label": "Green"
    }
  ]
}

date

A question that displays a text field that only accepts date entry. Used for questions that must be answered with a date.

Note: format is required when using this screener question type. The format must be dd/MM/yyyy or another locale specific format that meets Unicode CLDR formatting. Indeed uses the SimpleDateFormat, so month must be formatted as MM. Using mm will result in misconfiguration.

date example

{
  "id":"startdate",
  "required":true,
  "type":"date",
  "question":"Start date?",
  "format":"dd/MM/yyyy",
  "min":"01/02/2014",
  "max":"03/04/2014"
}

file

A question that displays a file upload interface. Used for questions that require a file upload as an answer, such as certifications, portfolios, or example work. As detailed in the Application data delivery options section, the answer data returned in the JSON POST request will contain 3 fields: contentType, data, and fileName.

Accepted file types: doc, docx, gif, jfif, jif, jpe, jpeg, jpg, pdf, png, rtf, tif, tiff, txt
File size limit: 5 MB (maximum combined limit per application is 15MB, including resume file.)

Note: Do not use this question type to acquire resumes. Instead, use the native “Resume” Indeed Apply configuration parameter.

file example

{
  "id": "file2",
  "type": "file",
  "question": "Please attach a resume file.",
  "required": true,
  "min":"1",
  "max": "3"
}

information

A text display that does not require a response. Used to include explanatory text or provide section headings. You can include the following HTML elements in the text: <b>, <p>, <br>, <li>, <ul>, <ol>, <a href=" ">. (Only http and https protocols are allowed in URLs. Links open in a new tab.)

Note: Do not force line breaks. Indeed automatically inserts line breaks between paragraphs.

information example

[{
  "id": "first_header",
  "type": "information",
  "text": "The next set of questions are <b> optional </b> and are for recording purposes only. 
 Make sure to view the <a href='http://www.eeoc.gov/employers/upload/poster_screen_reader_optimized.pdf'> EEO is the Law</a> poster.",
  "fontsize": 8
}]

pagebreak

Used to group questions on a page. All questions included between two pagebreak types appear on the same page. You can group up to 20 questions on the same page.

pagebreak example

[{
    "id": "page1_open",
    "type": "pagebreak"
  },
  {
    "id": "question_sample",
    "type": "text",
    "question": "Age?"
  },
  {
    "id": "page1_close",
    "type": "pagebreak"
  }
]

Next steps