JSON Interview Documentation

ZR ATS Integration Team

Version 1.1, 2018-02-13

Table of Contents
Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1  

1. Interview Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

1.1. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

1.2. Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

1.2.1. Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
 

1.2.2. Integer and Decimal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3  

1.2.3. Date. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 

1.2.4. Select and Multi-Select . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

1.2.5. Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

1.3. Example Interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

2. Answer Delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

2.1. JSON Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

2.2. Answer Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

2.2.1. Answer Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

2.3. Example Answers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10  
 ZipRecruiter JSON Interview Documentation v1.1

Introduction
This document defines the expected format for ZipRecruiter Applicant Interviews, sometimes
known as screening or pre-screening questions — a short series of questions presented to your
applicants during the application process.

This format is primarily an extension to XML Job Feeds and is not necessary for most applications
of job feeds. It also complements and extends our ZipRecruiter Apply Webhook integration, by
sending the applicant’s answers direct to your ATS platform.

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

Introduction 1
 ZipRecruiter JSON Interview Documentation v1.1

1. Interview Specification
An interview to be attached to a job listing is expressed as an array of objects, each object
representing a question, in JSON format. See Example Interview for a complete interview example,
and our XML Feed Documentation for an example of how an interview is embedded in your job
feed, attached to a job listing.

1.1. 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. The current version of this
schema can always be found at the URL below.

• https://static.ziprecruiter.com/schema/interview-schema.json

The following tools can be used from a web browser to test a JSON document against a JSON
Schema.

• JSON Schema Lint

• JSON Schema Validator

Be aware that JSON Schema is currently in an ongoing draft process, and tools may not support the
most recent draft specification. Most schemas can be translated back to older drafts in order to
support outdated tools.

1.2. Questions
Example Question

{
  "id": "color",
  "type": "select",
  "question": "What is your favorite color?",
  "options": [
  { "value": "blue", "label": "Blue" },
  { "value": "red", "label": "Red" },
  { "value": "green", "label": "Green" }
  ]
}

The following fields are available in all questions, regardless of type. All are required except for
required. All fields should be text values unless specified otherwise.

id
A unique identifier for this question. This can just be the ordinal number of the question (i.e. 1,
2, 3…) if you don’t use an ATS integration and don’t already have an identifier for your
questions. If you do use an ATS integration, this identifier is returned to you alongside candidate

1. Interview Specification 2
 ZipRecruiter JSON Interview Documentation v1.1

answers for your ATS platform to match those answers back to their questions.

type
The question type, which determines the appearance of the question to your applicants, as well
what other fields are required and optional for the question here. The following types are valid:

• text
• integer
• decimal
• date
• select
• multiselect
• upload

Each type may have further required and allowed fields; click or see below for more
information.

question
The question text shown to applicants. Simple HTML formatting, like paragraphs and emphasis,
is permitted. For compatibility, multiselect questions must use questions instead of this field.

required
Boolean, Optional. If present and true, this question cannot be skipped by applicants, and is
required in order for the application to be considered complete and delivered to you.

1.2.1. Text

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

min
max
The minimum and maximum number of characters required to accept an answer.

limit
An alias for max.

Example Text Question

{
  "id": "923124",
  "type": "text",
  "question": "What is your pet's name?",
  "required": true
}

1.2.2. Integer and Decimal

An entry restricted to numeric input, optionally with decimal fractions, as well as minimum and

1. Interview Specification 3
 ZipRecruiter JSON Interview Documentation v1.1

maximum value requirements. For compatibility, this is expressed as an extension of the text type.

type
Must be text.

format
Must be either integer or decimal.

min
max
The minimum and maximum value required. It’s recommended that these fields be expressed as
text, despite numeric literals being available in JSON.

These limits are not suitable for marking the correct answer to a math question, as applicants
are told these limits and cannot proceed to the next question without an answer within them.

Example Decimal Question

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

1.2.3. Date

A date entry with optional earliest and latest date requirements. For compatibility reasons, this is
expressed as an extension of the text type.

min
max
The earliest and latest date accepted, in dd/MM/yyyy format. Applicants will be shown a date-
picker that restricts them to this range.

format
Required, must be dd/MM/yyyy. All date answers are recorded and transmitted as dd/MM/yyyy,
while your ZipRecruiter account or ATS will display them in the local format. This is required in
order to be clear that only one date format supported.

1. Interview Specification 4
 ZipRecruiter JSON Interview Documentation v1.1

Example Date Question

{
  "id": "921200",
  "type": "date",
  "question": "When was your pet adopted, or born into your care?",
  "min": "01/01/1970",
  "format": "dd/MM/yyyy"
}

1.2.4. Select and Multi-Select

A list of options where either only one may be selected, or any number of options may be selected.

Multi-select questions require their question text in the questions key, rather than
 question. This is required for compatibility.

options
An array of objects, each with both of the following fields:

label
The option text shown to applicants.

value
The corresponding value, or option identifier that is returned to your ATS in answers, if
applicable.

Example Select Question

{
  "id": "612841",
  "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"}
  ]
}

1. Interview Specification 5
 ZipRecruiter JSON Interview Documentation v1.1

Example Multi-Select Question

{
  "id": "612842",
  "type": "multiselect",
  "questions": "What colors are present on your pet's nose?",
  "options": [
  {"value": "0", "label": "Pink"},
  {"value": "1", "label": "Brown"},
  {"value": "2", "label": "Liver"},
  {"value": "3", "label": "Yellow"},
  {"value": "4", "label": "Green"},
  {"value": "5", "label": "None of the Above"}
  ]
}

1.2.5. Upload

A file upload entry. Files from applicants for upload questions are limited to PDF and well-known
image and text document formats, and may be no larger than 10MB. No additional fields are
required.

Example Upload Question

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

1. Interview Specification 6
 ZipRecruiter JSON Interview Documentation v1.1

1.3. Example Interview

[
  {
  "id": "923124",
  "type": "text",
  "question": "What is your pet's name?",
  "required": true
  }, {
  "id": "2894492",
  "type": "text",
  "format": "decimal",
  "question": "What is your pet's weight, in kg?",
  "min": "0.01",
  "max": "250"
  }, {
  "id": "921200",
  "type": "date",
  "question": "When was your pet adopted, or born into your care?",
  "min": "01/01/1970"
  }, {
  "id": "612842",
  "type": "multiselect",
  "question": "What colors are present on your pet's nose?",
  "options": [
  {"value": "0", "label": "Pink"},
  {"value": "1", "label": "Brown"},
  {"value": "2", "label": "Liver"},
  {"value": "3", "label": "Yellow"},
  {"value": "4", "label": "Green"},
  {"value": "5", "label": "None of the Above"}
  ]
  }, {
  "id": "7762353",
  "type": "upload",
  "question": "Please submit your cutest photo of your pet.",
  "required": true
  }
]

1. Interview Specification 7
 ZipRecruiter JSON Interview Documentation v1.1

2. Answer Delivery
All applicant answers to interview questions managed using this system appear in your
ZipRecruiter account and notification e-mails just as if you had added the interview manually.

Additionally, we can support a standard webhook which allows your applicants to ZipRecruiter
Apply, as well as ATS platform integrations, delivering candidates and their responses directly to
you.

The answer format sent by that webhook is detailed here, but please contact us for more
information.

2.1. JSON Schema

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

• https://static.ziprecruiter.com/schema/answers-schema.json

2.2. Answer Specification

Interview answers are produced as an array of answer objects, all with an id field. This array is
very likely to arrive in the same order as your interview questions, but you should use the id field
to match answers back to their questions rather than rely on this.

Answers that are not required may be omitted. If an applicant fails to answer a required question,
no answers or application will be delivered.

2.2.1. Answer Fields

id
Required. This is the question id this 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, this will be present instead of value. It contains an array of strings
corresponding to the values of the options selected by the applicant.

filename
For upload questions, this is the original attachment filename.

2. Answer Delivery 8
 ZipRecruiter JSON Interview Documentation v1.1

2.3. Example Answers

[
  {
  "id": "923124",
  "value": "Spot"
  }, {
  "id": "2894492",
  "value": "25.0"
  }, {
  "id": "921200",
  "value": "04/01/2011"
  }, {
  "id": "612842",
  "values": ["0", "2"]
  }, {
  "id": "7762353",
  "filename": "spot.jpg",
  "value": "[Base-64 data omitted]"
  }
]

2. Answer Delivery 9
 ZipRecruiter JSON Interview Documentation v1.1

Contact Information
If you have questions about JSON interviews or job feeds, please don’t hesitate to contact us.

Email: [email protected]

If you have questions about ATS Integrations and Partnerships, contact us or find more info here:

Web: https://www.ziprecruiter.com/ats-partners
Email: [email protected]

Contact Information 10