Screener Questions Specification

This document defines the expected format for ZipRecruiter Applicant Screener Questions (previously known as "Interview") — a short series of questions presented to applicants during the application process.

This format is primarily an extension to XML Job Feeds and not necessary for the API integrations. It also complements and extends the Apply Webhook integration, by sending the applicant's answers directly to your ATS platform.

Screener Questions should be provided in JSON format, as a URL in the XML Job Feed. See Feed Import — Applicant Screening Questions for details on how to include them in your feed.

note

If you're interested in using this feature, please contact us for assistance.

JSON Schema

This specification is also expressed as a JSON Schema document, which is used for input validation at ZipRecruiter, and can be used for output and testing validation.

Download screener-questions-schema-v2.json

You can validate your JSON against the schema using the JSON Schema Validator on the References page, or with external tools like JSON Schema Lint or JSON Schema Validator.

Question Parameters

Screener questions are expressed as an array of JSON objects, each object representing a question. The following fields are available, and required attributes are marked with an asterisk (*). All fields should be text values unless specified otherwise.

Question parameters reference

Field	Description	Values	Example
`id` *	A unique identifier for this question. If you use an ATS integration, this identifier is returned alongside candidate answers for your ATS platform to match answers back to their questions.	Any string	`"id": "abc-123"`
`type` *	The question type. Determines the appearance of the question and what fields are required/optional.	`text`, `textarea`, `integer`, `decimal`, `date`, `select`, `radio`, `multiselect`, `checkbox`, `upload`, `information`, `pagebreak`, `question_group`	`"type": "text"`
`question` *	The question text displayed to applicants during the apply flow. Basic HTML formatting (paragraphs, emphasis) is permitted. Not required for `pagebreak` and `information` types.	Any string	`"question": "What is your pet's name?"`
`text`	Required for type `information`. The informational text to display. Not supported for other types.	Any string	`"text": "Please answer below"`
`required`	Optional boolean. If `true`, the question cannot be skipped by applicants and must be answered for the application to be considered complete.	`true` / `false`	`"required": true`
`repeatable`	Optional boolean. If `true`, the question can have multiple answer blocks.	`true` / `false`	`"repeatable": true`
`format`	Required for type `text` with `integer` or `decimal` values. Optional for type `date` — defaults to `MM/dd/yyyy` if omitted.	For `text`: `integer`, `decimal`. For `date`: `YYYY-MM-DD`, `yyyy-MM-dd`, `MM/dd/yyyy`, `dd/MM/yyyy`, `M/d/yyyy`, `MM-dd-yyyy`, `dd-MM-yyyy`.	`"format": "YYYY-MM-DD"`
`min`	For `text` — minimum character count. For `integer`/`decimal` — minimum value. For `date` — earliest date accepted. For `question_group` — minimum number of answer blocks.	Varies by type	`"min": 10`
`max`	For `text` — maximum character count. For `integer`/`decimal` — maximum value. For `date` — latest date accepted. For `question_group` — maximum number of answer blocks.	Varies by type	`"max": 100`
`limit`	For `text`/`textarea` — character limit for the answer (alias for `max`).	Any integer	`"limit": 100`
`options`	Required for `select`, `radio`, `multiselect`, and `checkbox` types. An array of objects, each with `label` (text shown to applicants), `value` (returned in answers), and optionally `is_correct` (for dealbreakers).	JSON array	See examples below
`dealbreaker`	Optional boolean for `select`, `multiselect`, `radio`, `checkbox` types. If `true`, the question is a dealbreaker — must be `"required": true`, and options with `"is_correct": false` disqualify the applicant.	`true` / `false`	`"dealbreaker": true`
`condition`	Makes the question conditional on the answer to a previous parent question. Contains `id` (parent question ID) and `value` (required answer value). The parent question must be in the same question group.	JSON object	See Conditional Questions
`questions`	Required for `question_group` type. Contains the list of sub-questions to display within the group.	JSON array	See Question Group

Supported Question Types

Text

A free-form text entry with optional minimum, maximum, and limit requirements.

JSON example

{
  "id":       "pet_name",
  "type":     "text",
  "question": "What is your pet's name?",
  "required": false,
  "min":      3,
  "max":      10
}

Textarea

A free-form multi-line text entry with optional limit (or max) for text length requirements.

JSON example

{
  "id":       "pet_features",
  "type":     "textarea",
  "required": false,
  "question": "Describe your pet?",
  "limit":    1000
}

limit and max are interchangeable for this type.

Integer

An entry restricted to numeric input with optional minimum and maximum value requirements. Can be expressed as an extension of the text type or as a standalone type.

Integer example (standalone type)

{
  "id":       "pet_age",
  "type":     "integer",
  "required": false,
  "question": "How old is your pet, in years?",
  "min":      1,
  "max":      25
}

Integer example (text type with format)

Or equivalently using the text type with format:

{
  "id":       "pet_age",
  "type":     "text",
  "format":   "integer",
  "question": "How old is your pet, in years?",
  "min":      1,
  "max":      25
}

Decimal

An entry restricted to numeric input with decimal fractions, as well as optional minimum and maximum value requirements. Can be expressed as an extension of the text type or as a standalone type.

Decimal example (standalone type)

{
  "id":       "pet_weight",
  "type":     "decimal",
  "question": "What is your pet's weight, in kg?",
  "min":      0.00,
  "max":      25.0
}

Decimal example (text type with format)

Or equivalently:

{
  "id":       "pet_weight",
  "type":     "text",
  "format":   "decimal",
  "question": "What is your pet's weight, in kg?",
  "min":      0.01,
  "max":      250
}

Date

A date entry with optional earliest and latest date requirements.

JSON example

{
  "id":       "pet_adopt_date",
  "type":     "date",
  "question": "When was your pet adopted, or born?",
  "format":   "dd/MM/yyyy",
  "min":      "22/01/2020",
  "max":      "31/03/2024"
}

note

The format field is optional and defaults to MM/dd/yyyy if omitted. Supported values: YYYY-MM-DD, yyyy-MM-dd, MM/dd/yyyy, dd/MM/yyyy, M/d/yyyy, MM-dd-yyyy, dd-MM-yyyy.

Select and Radio

A list of options where only one may be selected as an answer. select renders as a dropdown, radio renders as radio buttons.

Select example

{
  "id":       "pet_sleep_pref",
  "type":     "select",
  "question": "Where does your pet like to sleep?",
  "options":  [
    {"value": "bed",   "label": "My Bed"},
    {"value": "floor", "label": "The Floor"},
    {"value": "alone", "label": "Its Bed"},
    {"value": "na",    "label": "None of the Above"}
  ]
}

Radio example

The radio type uses the same structure but renders differently:

{
  "id":       "pet_sleep_pref",
  "type":     "radio",
  "question": "Where does your pet like to sleep?",
  "options":  [
    {"value": "bed",   "label": "My Bed"},
    {"value": "floor", "label": "The Floor"},
    {"value": "alone", "label": "Its Bed"},
    {"value": "na",    "label": "None of the Above"}
  ]
}

Multiselect and Checkbox

A list of options where any number of options may be selected as answers. multiselect renders as a multi-select dropdown, checkbox renders as checkboxes. Options need to include a label and value. The label is the text shown to applicants. The value is the corresponding value, or option identifier that is returned to your ATS in answers, if applicable.

Multiselect example

{
  "id":       "pet_nose_colors",
  "type":     "multiselect",
  "question": "What colors are present on your pet's nose?",
  "options":  [
    {"value": "0", "label": "Pink"},
    {"value": "1", "label": "Brown"},
    {"value": "5", "label": "None of the Above"}
  ]
}

Checkbox example

The checkbox type uses the same structure:

{
  "id":       "pet_nose_colors",
  "type":     "checkbox",
  "question": "What colors are present on your pet's nose?",
  "options":  [
    {"value": "0", "label": "Pink"},
    {"value": "1", "label": "Brown"},
    {"value": "5", "label": "None of the Above"}
  ]
}

Upload

A file upload entry. Files from applicants are limited to PDF, PNG, JPEG, DOCX, and DOC, and should be no larger than 10MB. No additional fields are required.

JSON example

{
  "id":       "pet_photo",
  "type":     "upload",
  "question": "Please submit your cutest photo of your pet.",
  "required": true
}

Information

Text that is displayed to the applicant but does not require any answer or response. Uses the text field instead of question.

JSON example

{
  "id":   "pet_info",
  "type": "information",
  "text": "Thank you for submitting your pet data"
}

Question Grouping

By default each question is displayed on a separate page one after the other. If you need to display multiple questions on a single page, there are two options:

Use type pagebreak — without repeatable groups
Use type question_group — with repeatable groups

warning

Do not mix pagebreak and question_group — only use one of them throughout the list of questions for a given job.

Pagebreak

No answer is expected for pagebreak type questions. This is used to indicate where the question grouping starts and ends. All questions included between the pagebreak types are displayed on the same page. Because a pagebreak starts a new group, never place one between a conditional question and the parent question it references.

Pagebreak example

[
  {
    "id":       "page1-info",
    "type":     "information",
    "text":     "Name and Age"
  },
  {
    "id":       "page1-question1",
    "type":     "text",
    "question": "What's your name?"
  },
  {
    "id":       "page1-question2",
    "type":     "integer",
    "question": "What's your age?"
  },
  {
    "id":       "pagebreak-1",
    "type":     "pagebreak"
  },
  {
    "id":       "page2-info",
    "type":     "information",
    "text":     "Phone and Email"
  },
  {
    "id":       "page2-question1",
    "type":     "text",
    "question": "What's your phone number?"
  }
]

Question Group

Groups are a set of questions presented together on a single page, similar to pagebreak but with the added feature that the entire group can be marked as repeatable (enabling applicants to provide multiple answer blocks). The questions field within the group contains the list of sub-questions to display.

note

Each question group is limited to a maximum size of 2MB.

Question group example

{
  "id":         "language_skills",
  "type":       "question_group",
  "question":   "Languages",
  "repeatable": true,
  "questions":  [
    {
      "id":   "title",
      "type": "information",
      "text": "List your language skills"
    },
    {
      "id":       "language",
      "type":     "text",
      "question": "Language"
    },
    {
      "id":       "level",
      "type":     "select",
      "question": "Proficiency",
      "options":  [
        {"label": "Expert", "value": "Expert"},
        {"label": "Beginner", "value": "Beginner"},
        {"label": "Intermediate", "value": "Interm"}
      ]
    }
  ]
}

Conditional Questions

A conditional question is presented to the applicant depending on the answer to a previous parent question. If the condition is met (i.e., the answer to the previous question matches the expected value in the condition), then the question is presented; otherwise it is not presented to the applicant.

warning

The parent question referred to in the condition must appear before the conditional question and be part of the same group — the same question_group, or the same page between two pagebreak entries. A pagebreak (or a question_group boundary) between a conditional question and its parent places them in different groups.

If you submit questions in this state, the entire set of questions for the job is rejected — not just the offending question. None of the questions are saved; the job stays published with no screening questions attached, so applicants are never asked them and no answers are delivered to your ATS. This applies whether the affected question is required or not.

Conditional question example

{
  "id":        "math_skills",
  "type":      "question_group",
  "question":  "Math knowledge question",
  "questions": [
    {
      "id":       "parent_question_id",
      "type":     "select",
      "question": "Do you know basic math?",
      "options":  [
        {"label": "Yes", "value": "1"},
        {"label": "No", "value": "0"}
      ]
    },
    {
      "id":        "child_question_id",
      "type":      "integer",
      "question":  "what is 1 + 1?",
      "condition": {
        "id":    "parent_question_id",
        "value": "1"
      }
    }
  ]
}

Dealbreaker Questions

A dealbreaker question marks the application as disqualified if the provided answer does not qualify based on the available options. A question can be set as dealbreaker using the dealbreaker field for the question types: select, multiselect, radio, checkbox.

Dealbreaker questions must be marked as "required": true, and any incorrect options should be specified as "is_correct": false; otherwise all other answers are considered correct.

For the multiple-choice types (multiselect / checkbox), selecting any option marked "is_correct": false disqualifies the applicant, regardless of which other options are also selected.

Dealbreaker question example

{
  "id":          "age",
  "type":        "select",
  "question":    "Are you at least 18 years old?",
  "dealbreaker": true,
  "required":    true,
  "options":     [
    {
      "value":      "0",
      "label":      "Yes",
      "is_correct": true
    },
    {
      "value":      "1",
      "label":      "No",
      "is_correct": false
    },
    {
      "value": "2",
      "label": "Prefer not to answer"
    }
  ]
}

Answer Delivery

All applicant answers to screening questions managed using this system are delivered through the Apply Webhook integration using the standard Apply Webhook format, delivering candidates and their responses directly to you.

Please contact us for more information.

Answer JSON Schema

Similar to Screener Questions, a JSON Schema is published for Answers as well.

Download answers-schema-v2.json

Answer Fields

Each answer object contains an id field matching the question it responds to, plus one of the following value fields:

Answer fields reference

Field	Description
`id`	Required. The question `id` this answer responds to.
`value`	For any question type except multiple-choice, multiple-answer, and upload: this is the verbatim answer given by the applicant. For multiple-choice questions, this is the `value` of the selected option, rather than the label. For upload questions, this is a base-64 encoded file stream, without whitespace.
`values`	For multiple-answer questions. An array of strings corresponding to the `value`s of the options selected by the applicant.
`filename`	For upload questions. The original attachment filename.
`entries`	For repeatable questions. Contains the answer entries for the repeatable question.
`answer_group`	For `question_group` type. Contains the list of answers.

Example Answers

Example answer payload

{
  "answers": [
    {
      "id":    "pet_name",
      "value": "tiger"
    },
    {
      "id":     "pet_nose_colors",
      "values": ["0", "1"]
    },
    {
      "id":       "pet_photo",
      "value":    "JVBERi0xLjUK...",
      "filename": "pet.pdf"
    },
    {
      "id":      "language_skills",
      "answer_group": [
        {
          "language": ["English"],
          "level":    ["Expert"]
        },
        {
          "language": ["Spanish"],
          "level":    ["Beginner"]
        }
      ]
    }
  ]
}

JSON Schema​

Question Parameters​

Supported Question Types​

Text​

Textarea​

Integer​

Decimal​

Date​

Select and Radio​

Multiselect and Checkbox​

Upload​

Information​

Question Grouping​

Pagebreak​

Question Group​

Conditional Questions​

Dealbreaker Questions​

Answer Delivery​

Answer JSON Schema​

Answer Fields​

Example Answers​

JSON Schema

Question Parameters

Supported Question Types

Text

Textarea

Integer

Decimal

Date

Select and Radio

Multiselect and Checkbox

Upload

Information

Question Grouping

Pagebreak

Question Group

Conditional Questions

Dealbreaker Questions

Answer Delivery

Answer JSON Schema

Answer Fields

Example Answers