XML Job Feed Requirements

This article outlines the XML job feed requirements for importing jobs into Handshake from an external applicant tracking system (ATS) or career site.

If you have questions while building or updating your feed, contact your Customer Success Manager (CSM). 

Job feed requirements 

File structure

When building your job feed, keep the following requirements in mind:

• The feed must be provided as a URL pointing to your XML file.
• The XML must have a root element, and the root element can have any name.
• The root element must contain a list of job elements for the jobs to be imported.

Both of the following XML structures are valid:

<source>
<build_date>02-02-2025</build_date>
<job>...</job>
<job>...</job>
</source>

<jobs>
<job>...</job>
</jobs>

Job structure

Your feed can include additional fields, but Handshake ignores fields that are not supported. Field names and accepted values should match exactly whenever possible.

If you cannot provide exact field name matches, you can use Field Name Mapping during XML feed setup.

Note: The <job> element is the exception to field mapping. It is case-sensitive and cannot be remapped. Your feed must use <job> and </job> in lowercase exactly as shown.

Required fields

• Title
  • Job title
  • Maximum 150 characters
• Description
  • Job description
  • Maximum 50,000 characters
  • Can be plain text or HTML
• Source_reference 
  • Unique identifier for the job in your source system
    Maximum 255 characters
    Accepted characters: letters, numbers, dashes (-), and underscores (_)
     

Conditionally required fields

The following fields are required only in certain cases.

country

• Required for Onsite and Hybrid

state

• Required for Onsite and Hybrid

city

• Required for Onsite and Hybrid

duration

• Required either in the <duration> tag or mentioned in the job description
• Accepted values: Permanent, Temporary

start_date

• Required when duration is Temporary
• Must use ISO 8601 format

end_date

• Required when duration is Temporary
• Must use ISO 8601 format

salary

• Required either in the <salary> tag or mentioned in the job description
• Required only for jobs in certain US states and district. 
• For the full list and salary formatting requirements, go to Salary structure.

Optional fields

location_type

• Accepted values: Onsite, Remote, Hybrid
• If omitted, Handshake defaults this value to Onsite

apply_url

• The URL where applicants will be redirected to apply.
• If omitted, the job is created as Apply on Handshake, and candidates are not redirected to your career site

employment_type

• Accepted values: Full-Time, Part-Time

job_type

• Accepted values: Job, Internship, Cooperative Education, Experiential Learning, Volunteer, Fellowship, Graduate School

All child elements within a <job> can use text or CDATA XML data types.

Example: single job

<jobs>
<job>
  <title>Service Technician</title>
  <description><![CDATA[The responsibilities of the job include ...]]></description>
  <source_reference>job_1234</source_reference>
  <location_type>Onsite</location_type>
  <country><![CDATA[United States of America]]></country>
  <state>Oregon</state>
  <city>Portland</city>
  <apply_url><![CDATA[https://jobsite.com/job/123/description.html]]></apply_url>
  <duration>Permanent</duration>
  <employment_type><![CDATA[Part-Time]]></employment_type>
  <job_type>Job</job_type>
  <salary>...</salary>
</job>
</jobs>

Salary structure

Salary transparency is legally required for jobs in the following US states and district:

• California
• Colorado
• New York
• Washington
• Hawaii
• Maryland
• Illinois
• Minnesota
• Vermont
• Massachusetts
• District of Columbia

If salary is not provided in a <salary> tag, it must be clearly stated in the job description.

Salary fields

schedule

• Accepted values: Annual, Monthly, Hourly

range

• Contains two child elements: min and max 
• If range is missing, exact is required

min

• Numeric value greater than 0

max

• Numeric value less than 100,000,000

exact

• Numeric value between 0 and 100,000,000 
• If exact is missing, range is required

currency

• Accepted values: USD, EUR, GBP

Example: salary range

<jobs>
<job>
  ...
  <salary>
    <schedule>Annual</schedule>
    <range>
      <min>60000</min>
      <max>90000</max>
    </range>
    <currency>EUR</currency>
  </salary>
</job>
</jobs>

Example: exact salary

<jobs>
<job>
  ...
  <salary>
    <schedule>Hourly</schedule>
    <exact>50</exact>
    <currency>USD</currency>
  </salary>
</job>
</jobs>

Location structure

If a job is available in multiple locations, you can include up to 50 locations per job.

Use the following format:

<locations>
<location>
  <city>Denver</city>
  <state>Colorado</state>
  <country>USA</country>
</location>
<location>
  <city>Santa Monica</city>
  <state>California</state>
  <country>USA</country>
</location>
</locations>

For a single-location job, either of the following formats is accepted.

Example: single location inside <location>

<job>
<location>
  <city>Denver</city>
  <state>Colorado</state>
  <country>USA</country>
</location>
</job>

Example: single location as direct child fields

<job>
<city>Denver</city>
<state>Colorado</state>
<country>USA</country>
</job>

Common reasons validation may fail

Validation may fail if:

Required job information is missing

The feed does not contain all required job information, or Handshake cannot successfully map that information during setup.

Fields such as title, description, source reference, location details, apply link, and other supported job fields do not need to use Handshake’s exact field names. However, that information still needs to be present somewhere in the feed and able to be mapped correctly during setup.

If the required information is missing entirely, appears blank, or cannot be clearly identified through mapping, validation may fail.

Some values are not in the expected format

Examples include:

• dates not using the expected format
• unsupported values for fields such as employment type or job type
• source references that include unsupported characters
• salary data that does not follow the expected structure

A field is present, but its contents do not match the type of information Handshake expects

Examples include:

• a field mapped as an apply link that does not contain a usable URL
• a field mapped as a location field that contains incomplete or inconsistent location data

Field mapping does not clearly connect the feed fields to the required Handshake job fields

This can happen when:

• field names are unclear
• multiple feed fields appear to represent the same Handshake field
• the mapped field does not consistently contain the expected type of data across jobs

The file opens, but one or more job records cannot be reliably processed

For example, the XML may be structurally valid, but individual job records may contain malformed HTML, incomplete nested data, or inconsistent formatting that prevents Handshake from confidently importing the jobs.

Field name mapping 

If your job feed uses different field names than the supported fields listed in this article, you can map them during XML feed setup in your Handshake portal.