Feed Import

Overview

Feed Import allows partners to post and manage jobs in bulk via an XML feed. Instead of using the REST API to manage jobs individually, you provide a hosted XML file containing all your open jobs, and ZipRecruiter processes it automatically on a regular schedule.

Requirements

note

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.

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.

Minimum Requirements for Jobs to be Delivered

Minimum required fields

Field	Description
`referencenumber`	Must be unique for each job and less than 64 characters.
`title`	Must be at least 3 characters.
`country`	Acceptable values are `US`, `CA`, `AU`.
`city` and `state`	Required if `postalcode` is not provided.
`postalcode`	Required if `city` and `state` are not provided.
`description`	Must be at least 25 characters.

You may include additional optional fields such as jobtype, experience, or interview_json. If included, these fields must contain only the explicit values noted in this document, otherwise the job will be rejected.

Example Feed

Example XML 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>
    <requisition_id>a-job-requisition-id-123</requisition_id>
    <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>
    <!-- Candidate Delivery Field (use only one of email or url) -->
    <email>where-to-email-applications@example.com</email>
    <!-- Additional Optional Fields -->
    <address>1615 Ocean Ave</address>
    <jobtype>Full-Time</jobtype>
    <accept_remote>0</accept_remote>
    <experience>mid</experience>
    <education>ged</education>
    <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>
     <pto>1</pto>
    </benefits>
  </job>
  <!-- Further <job>s follow... -->
</source>

Optional Metadata Fields: These fields may be included for feed-compatibility with other systems.

Candidate Delivery Field: Only one of <email> or <url> should be specified per job. See Candidate Delivery Fields.

Additional Optional Fields: See Extended Job Fields

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.

Job fields reference

Field	Required	Description
`referencenumber`	Yes	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`	Yes	The job listing title.
`description`	Yes	Your full job description. 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`	Yes	The two-letter ISO country code where the position is located.
`city`	Conditional	Required unless `postalcode` is present. The city where the position is located. When provided, `state` must be provided as well. Where appropriate, this can also mean a Locality, Town, or Municipality.
`state`	Conditional	Required when `city` is present. The state or province where the position is located. Where appropriate, this can also mean a Province, Region, or District.
`postalcode`	No	Strongly encouraged over `city` and `state`. The Zip or Postal Code where the position is located. Providing a postal code will improve the quality of the job seekers matched with your position. We suggest only omitting this field if the position does not have a physical location.
`company`	No	The company actually hiring for the position. If not present, the default hiring company selected in the feed import tool will be shown. Avoid terms like "confidential" or "unknown," as vague company names are generally blacklisted by search engines.
`date`	No	The date when the job was first published on your system. When not present, the time of import will be used. Must be in ISO8601 (`2016-07-31T07:27:14`) or RFC1123 (`Thu, 31 Jul 2014 07:27:14 PDT`) format.
`post_url`	No	A dynamic candidate submission endpoint URL. Use this if the customer wants to provide a custom endpoint for candidate submissions.
`requisition_id`	No	A job identifier from the partner not required to be unique on ZipRecruiter's side, used for application delivery. Used when a single `requisition_id` on the partner's side maps to multiple jobs with unique `referencenumber`s on ZipRecruiter's side.

Candidate Delivery Fields

The following fields control candidate delivery. 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 per job.

Candidate Delivery Fields

Field	Required	Description
`email`	No	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`	No	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.

Extended Job Fields

All of the fields in this section are optional, but can improve the jobseeker experience and candidate quality for your listings. These fields increase your search visibility as well as provide more detail to candidates in terms of compensation and requirements.

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.

warning

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.

Location

Field	Description
`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.
`accept_remote`	Indicates that the job can be performed remotely. If excluded, our search engine will attempt to infer it from keywords in your job description, so we recommend including a value for every job. Acceptable values: `1` or `0`.

Employment and Compensation

Field	Description
`jobtype`	The employment type offered. Acceptable values: `Full-Time`, `Part-Time`, `Contractor`, `Temporary`, `Per Diem`, `Other`. Case-insensitive.
`employment_type`	Available as an alias for `jobtype`.
`compensation_interval`	The payment interval for compensation values. Acceptable values: `Annually`, `Monthly`, `Weekly`, `Daily`, `Hourly`. Case-insensitive.
`compensation_min`	Minimum compensation offered per interval. Use a period (ASCII 0x2E) as decimal separator. Must be less than or equal to `compensation_max`.
`compensation_max`	Maximum compensation offered per interval. Use a period (ASCII 0x2E) as decimal separator. Commas (ASCII 0x2C) are accepted for optional grouping.
`compensation_has_commission`	If present with any content other than `0`, adds the label "Plus Commission" alongside the listed compensation.
`compensation_currency`	The currency for compensation. Acceptable values: `USD`, `CAD`, `AUD`. Required if `compensation_min`/`compensation_max` is provided.

Benefits

Simple benefits info can be added to your job listing with a <benefits> tag. Each sub-tag, if present with any content other than 0, indicates the benefit is offered. Tags that are absent will not be shown on your job listing.

Tag	Benefit
`vision`	Vision insurance
`medical`	Medical insurance
`dental`	Dental insurance
`life_insurance`	Life insurance
`retirement_savings`	Retirement savings plan
`pto`	Paid time off

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

Applicant Requirements

Field	Description
`resume_not_required`	If present with any content other than `0`, applicants will not need a resume. Barring other requirements, you'll accept applicants with only name, email, and phone.
`experience`	The experience level required. See values below.
`education`	The education level required. See values below.

Experience levels:

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 levels:

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

Applicant Screening Questions

Each job may have a series of screening questions for the candidate, and these questions can be specified in your job feed. The optional <interview_json> tag adds screening questions to the job. This tag should contain JSON content, and wrapping that JSON in a CDATA section is recommended. You may also use the <interview_url> tag interchangeably. See The Question Model 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.

For all new integrations and more complex question use cases, including grouped questions, conditional questions, repeatable questions, etc, we recommend using the Screener Questions Specification.

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>

Example Multi-Question Interview with grouping and conditionality, inside an XML snippet

<interview_json>
  <![CDATA[
    [
      {
        "id": "ParentQID",
        "type": "select",
        "question": "Do you want to answer next question?",
        "group_number":1,
        "options": [
          { "value": "Yes", "label": "Yes" },
          { "value": "No",  "label": "No" }
        ]
      },
      {
        "id": "ChildQID",
        "type": "select",
        "question": "Answer this question?",
        "group_number":1,
        "condition" : {
          "id" : "ParentQID",
          "value": "Yes"
        },
        "options": [
          { "value": "1", "label": "one" },
          { "value": "2", "label": "two" }
        ]
      }
    ]
  ]]>
</interview_json>

Example Job Feed (truncated) with interview_url

<job>
  <referencenumber>G3GRMVHTKAKBMF2T</referencenumber>
  <title>ADP Test Job</title>
  <description>Test job description</description>
  <interview_url>https://questions_url.com</interview_url>
</job>

If the <interview_json> tag is empty or missing, no changes to existing questions/answers will be made.

To remove all questions from an existing job, send an empty json array as the content of the tag, e.g. <interview_json> <![CDATA[ [] ]]> </interview_json>.

note

The Screener Questions Specification supports advanced features such as Conditional questions, Grouped questions, Dealbreaker questions, etc. If you intend to use these advanced features, please contact us before beginning implementation, to ensure seamless integration.

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.

XML example

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

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

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

Frequently Asked Questions

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.

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.

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.

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.

Are duplicate entries allowed?

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

Overview​

Requirements​

Minimum Requirements for Jobs to be Delivered​

Example Feed​

Job Fields​

Candidate Delivery Fields​

Extended Job Fields​

Location​

Employment and Compensation​

Benefits​

Applicant Requirements​

Applicant Screening Questions​

Partner Attributes​

Feed Updates & Delivery​

Frequently Asked Questions​

Overview

Requirements

Minimum Requirements for Jobs to be Delivered

Example Feed

Job Fields

Candidate Delivery Fields

Extended Job Fields

Location

Employment and Compensation

Benefits

Applicant Requirements

Applicant Screening Questions

Partner Attributes

Feed Updates & Delivery

Frequently Asked Questions