XML Feed Documentation

ZR Feeds Team

Version 1.4, 2018-12-11

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

1. Feed Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2  

1.1. Example Feed. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3  

2. Job Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
 

2.1. Candidate Delivery Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

2.2. Additional Optional Fields - Get More Exposure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5  

3. Feed Updates & Delivery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6  

4. Frequently Asked Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.1. How often will the feed be updated? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.2. How do I close jobs when using the XML feed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.3. Can I make changes to jobs using the ZipRecruiter web site? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.4. Should I specify a <url> or <email>? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.5. Can I "refresh" my old jobs by changing the dates? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

4.6. Are duplicate entries allowed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7  

5. Extended Job Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

5.1. Location. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 

5.2. Employment and Compensation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8  

5.3. Benefits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
 

5.4. Applicant Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9  

5.5. Applicant Interview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10  

5.6. Partner Attributes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10  

Contact Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11  

Appendix A: Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12  
 ZipRecruiter XML Feed Documentation v1.4

Introduction
ZipRecruiter aims to make the job posting process simple from end-to-end. This includes providing
the ability to automatically post your jobs from your website / applicant tracking system (ATS).
Outlined below are our specifications for submitting an XML feed of jobs. This is by far the fastest
and easiest way to submit jobs to ZipRecruiter.com.

Introduction 1
 ZipRecruiter XML Feed Documentation v1.4

1. Feed Requirements
A feed must consist of a <source> tag containing one or more <job> tags. All job content must be
inside CDATA sections or properly encoded with XML entities to avoid issues processing your XML
feed. All XML tags are case-insensitive unless otherwise specified.

Feeds must provide all currently open jobs, not jobs added since the last feed request. Jobs not
included in your feed will be removed from your account, our search results, and our network.

The referencenumber provided for each job must be unique to that job. The referencenumbers of
jobs found in your feed are compared to those on your ZipRecruiter account in order to determine
what jobs should be added, removed, or updated.

Please provide the proper character encoding for your feed in the XML header.
The [Example Feed] illustrates UTF-8, however this may or may not be the case for
 you. Please check with your system administrator if your need clarification. If
you’re not specifying the proper encoding, your listings may appear with unusual
characters.

1. Feed Requirements 2
 ZipRecruiter XML Feed Documentation v1.4

1.1. Example Feed

<?xml version="1.0" encoding="UTF-8"?>

<source>
  <!-- Optional Metadata Fields --> ①
  <lastBuildDate>Wed, 27 Aug 2014 01:49:49 GMT</lastBuildDate>
  <publisherurl>http://dev.ziprecruiter.com:4014</publisherurl>
  <publisher>ZipRecruiter</publisher>
  <!-- End Optional Metadata Fields -->
  <job>
  <referencenumber>a-unique-job-id-123</referencenumber>
  <title>Auto Tech.</title>
  <description><![CDATA[Hiring a skilled Auto Technician
<b>ASAP</b>!]]></description>
  <country>US</country>
  <city>Santa Monica</city>
  <state>CA</state>
  <postalcode>90755</postalcode>
  <company>Euro Car Care, Inc</company>
  <date>2014-07-31T07:27:14</date>
  <category><![CDATA[Construction/Skilled Trade]]></category>
  <!-- Candidate Delivery Fields --> ②
  <email>[email protected]</email>
  <url><![CDATA[http://jobs.dev.ziprecruiter.com:4014/job/Auto-
Tech/cc68d2f943/?source=ziprecruiter-feed]]></url>
  <!-- Additional Optional Fields --> ③
  <address>1615 Ocean Ave</address>
  <jobtype>Full-Time</jobtype>
  <experience>mid</experience>
  <education>ged</experience>
  <compensation_interval>hourly</compensation_interval>
  <compensation_min>24.00</compensation_min>
  <compensation_max>48.00</compensation_max>
  <compensation_currency>USD</compensation_currency>
  <benefits>
  <medical>1</medical>
  <dental>1</dental>
  <vision>0</vision>
  <life_insurance>1</life_insurance>
  <retirement_savings>0</retirement_savings>
  </benefits>
  </job>
  <!-- Further <job>s follow... -->
</source>

① These fields may be included for feed-compatibility with other systems.

② Normally only one of these [Candidate Delivery Fields] should be included, but both are shown
in this example.

③ See [Additional Optional Fields - Get More Exposure]

1. Feed Requirements 3
 ZipRecruiter XML Feed Documentation v1.4

2. Job Fields
Each <job> tag represents one job listing. The following are the core fields for jobs. Each should be a
single tag per job, containing nothing but the content for that field. See the [Example Feed] for
reference.

referencenumber
Required. A unique alphanumeric reference ID for the job listing, up to 64 characters in length.
Jobs exceeding this limit will be rejected from import.

title
Required. The Job listing title.

description
Required. Your full job description goes here. HTML markup is allowed and may be scrubbed
for security, and must comply with our terms. We may use this field for indexing and snippet
generation.

country
Required. The two-letter ISO country code where the position is located.

city
Required, unless postalcode is present. The city where the position is located. When provided,
state must be provided as well. Where appropriate, this field can also mean a Locality, Town, or
Municipality.

state
Required, when city is present. The state or province where the position is located. Where
appropriate, this field can also mean a Province, Region, or District.

postalcode
Optional, but preferred over city and state. The Zip or Postal Code where the position is located.

company
Optional. The company actually hiring for the position. If not present, the default hiring
company selected in the feed import tool will be shown for this job. Avoid terms like
"confidential" or "unknown," as vague company names are generally blacklisted by search
engines.

date
Optional, but recommended. The date provided for each job should indicate when the job was
first published on your system. When not present, the time of import will be used. Date should
be in either ISO8601 or RFC1123 format. That is, 2016-07-31T07:27:14 or Thu, 31 Jul 2014
07:27:14 PDT.

category
A category name matching one found in the [Categories] section.

2. Job Fields 4
 ZipRecruiter XML Feed Documentation v1.4

2.1. Candidate Delivery Fields

The following job fields control candidate delivery and describe general use cases. If you use an ATS
integration or have a special partnership with ZipRecruiter, you may be instructed to use these
fields differently. Only one of these fields should be specified in a job tag.

email
Optional. A hiring manager’s email address who should receive notices of new candidates for
this job. If absent, account defaults are used. Candidates are still tracked in your ZipRecruiter
account.

url
Optional. If present, candidates will be redirected to this URL when they wish to apply.
Redirected candidates do not see the option to use ZipRecruiter Apply and are not tracked in
your ZipRecruiter account.

If neither of these tags is present, candidates will be tracked in your ZipRecruiter account, but no
automatic email is sent informing you of new candidates.

2.2. Additional Optional Fields - Get More Exposure

We accept many more job fields that increase your search visibility as well as provide more detail
to candidates in terms of compensation and requirements.

See [Extended Job Fields] for information on additional job fields we can support. Adding job
address and compensation details is highly recommended for maximum visibility. These extended
fields include:

• [Location]

• [Employment and Compensation]

• [Benefits]

• [Applicant Requirements]

• [Applicant Interview], or pre-screening

2. Job Fields 5
 ZipRecruiter XML Feed Documentation v1.4

3. Feed Updates & Delivery

We require a full feed file, so that at any point in time you are specifying exactly which jobs you
would like to have included on your account. A feed URL that only returns jobs which are new or
changed since our last check will cause any prior jobs to be unposted from your account.

Our system will process the provided URL 4 times daily — 2 and 8, AM and PM, Pacific
time — checking for any changes and applying them if found.

We currently accept files delivered via HTTPS or HTTP, and can support "Basic" authentication.

3. Feed Updates & Delivery 6

 ZipRecruiter XML Feed Documentation v1.4

4. Frequently Asked Questions

4.1. How often will the feed be updated?
We’ll read and update your feed 4 times per day, approximately every 6 hours. It takes up to a few
hours for updates to propagate fully and 24-48 hours for the updates to reach our job board
partners. If your feed is preprocessed by a third party, this may introduce additional delays.

4.2. How do I close jobs when using the XML feed?

Remove the jobs you want to close from your XML feed, and they’ll be closed the next time the feed
is updated.

4.3. Can I make changes to jobs using the ZipRecruiter

web site?
Yes, you can update jobs posted via XML on the ZipRecruiter web site, but be aware that the next
time your feed is updated via XML, your job will be updated to match what’s in the XML, which
could overwrite any changes you made on the web site.

4.4. Should I specify a <url> or <email>?

Most users will want to specify an <email> which is the email address where we will send job
applicants who use our application page. If you prefer that applicants use another URL to apply for
the job, then you should specify a <url>. Only one of these tags may be specified, and if your feed is
for an ATS integration, you may be given further instructions pertaining to these tags.

4.5. Can I "refresh" my old jobs by changing the dates?

No. If the values in <date> are changed on a job that was previously imported, the Jobs folder will
show the date when the job was originally imported. However, we refresh the "posted on" date
shown to jobseekers every 30 days.

4.6. Are duplicate entries allowed?

No, duplicate listings within the same category and location will be filtered out automatically. If a
duplicate listing is found we will remove the old listing.

4. Frequently Asked Questions 7

 ZipRecruiter XML Feed Documentation v1.4

5. Extended Job Fields

All of the fields detailed in this section are optional, but can improve the jobseeker experience and
candidate quality for your listings. Everything listed here must be included inside the <job> tag for
each job to which it applies. Examples can be found in the [Example Feed].

If you use the exact same feed on other platforms, they may have trouble with
 these extended tags and require a copy of your feed without them.

5.1. Location
address
A street address to be displayed on your job listing. This can differentiate between locations in
the same postal code. Do not include city, state, or postal code in this field.

5.2. Employment and Compensation

jobtype
The employment type offered in this position. Acceptable values are Full-Time, Part-Time,
Contractor, Temporary, and Other. This field is case-insensitive.

employment_type
Available as an alias for jobtype.

compensation_interval
The payment interval that the following compensation values are listed in. For example $15
hourly or $65,000 annually. Acceptable values are Annually, Monthly, Weekly, Daily, and Hourly.
This field is case-insensitive.

compensation_min
compensation_max
Numeric values. The minimum and maximum compensation offered per interval, for this
position. This should be expressed with a period (ASCII 0x2E) as a decimal separator, and
commas (ASCII 0x2C) for optional grouping separators.

compensation_has_commission
If present, with any content other than 0, adds the label "Plus Commission" alongside the listed
compensation.

compensation_currency
The currency that compensation is provided in, and that the above values should be labeled
with. Must be a three-letter currency code. If not present, assumed to be USD. Acceptable values
are USD, CAD, and GBP.

5. Extended Job Fields 8

 ZipRecruiter XML Feed Documentation v1.4

5.3. Benefits
Simple benefits info can be added to your job listing with a <benefits> tag. This tag may contain any
of the following tags, which, if present with any content other than 0, will indicate the
corresponding benefit is offered with the position. Acceptable benefits tags are vision, medical,
dental, life_insurance, and retirement_savings. Any tags that are absent will not be shown as
benefits on your job listing.

Example

<benefits>
  <vision>1</vision>
  <medical>1</medical>
  <dental>1</dental>
  <life_insurance>1</life_insurance>
  <retirement_savings>1</retirement_savings>
</benefits>

5.4. Applicant Requirements

resume_not_required
If present, with any content other than 0, this job will not require applicants to include a resumé
to apply. Barring other requirements, this means you’ll accept applicants with only a minimum
of name, email, and phone.

experience
The experience level required for this position.

Feed Value Description

intern Intern
entry Entry Level (0-2 years)
mid Mid Level (3-6 years)
senior Senior Level (7+ years)
director Director
executive Executive

education
The education level required for this position.

Feed Value Description

ged High School Diploma/GED
assoc Associates Degree
undergrad Bachelors Degree
grad Masters or Ph. D

5. Extended Job Fields 9

 ZipRecruiter XML Feed Documentation v1.4

5.5. Applicant Interview

Each job may have a series of interview questions for the candidate, and this interview can be
specified in your job feed. The optional <interview_json> tag adds an interview to the job. This tag
should contain JSON content, and wrapping that JSON in a CDATA section is recommended. See
JSON Interview Specification for details on the expected JSON content.

If you have an ATS integration or other partnership, candidates' answers through interviews added
by feeds or through your ZipRecruiter account may also be sent to your ATS platform.

Example Single-Question Interview, inside an XML snippet.

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

5.6. Partner Attributes

Each job may include Partner Attributes, arbitrary key/value data that may be used for ATS
integrations or other custom behaviors. Within <partner_attributes>, tags of any name are allowed,
and any value is accepted, but tags may not be nested.

Example Partner Attributes

<partner_attributes>
  <tracking_code>r2d2c3po</tracking_code>
</partner_attributes>

5. Extended Job Fields 10

 ZipRecruiter XML Feed Documentation v1.4

Contact Information
If you have questions about XML import, 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 11
 ZipRecruiter XML Feed Documentation v1.4

Appendix A: Categories
• Accounting/Finance
• Admin/Secretarial
• Advertising
• Architect/Design
• Art/Media/Writers
• Automotive
• Banking
• Biotech/Pharmaceutical
• Computer/Software
• Construction/Skilled Trade
• Customer Service
• Domestic Help/Care
• Education
• Engineering
• Environmental Science
• Events
• Everything Else
• Facilities/Maintenance
• General Labor/Warehouse
• Gov/Military
• HR & Recruiting
• Healthcare
• Hospitality/Restaurant
• Information Technology
• Insurance
• Internet
• Law Enforcement/Security
• Legal
• Management & Exec
• Manufacturing/Operations
• Marketing/PR
• Nonprofit & Fund
• Oil/Energy/Power
• Quality Assurance
• Real Estate
• Research & Dev
• Retail
• Sales & Biz Dev
• Salon/Beauty/Fitness
Social Services

Appendix A: Categories 12
 ZipRecruiter XML Feed Documentation v1.4

• Supply Chain/Logistics
• Telecommunications
• Travel
• Trucking/Transport
• TV/Film/Musicians
• Vet & Animal Care
• Work from Home

Appendix A: Categories 13