Jobs XML Feed Specification

An XML file is used to describe currently available jobs openings. All valid tags are described below. Tag names must be given exactly as below, in English, while text in tag values can be given in any language, using UTF-8 encoding.

See the sample feed below for a complete working example.

Note that all string tags must have their values wrapped as CDATA, for example <![CDATA[Some Data]]>.

source tag

The <source> tag is the topmost tag in a feed. The following sub-tags are valid within it.

NameDescription

publisher-name

Type: string

Required

Max characters: 1000

The name of your organization. Plain text only.

publisher-url

Type: string

Required

Max characters: 1000

The URL of your organizations's website, including leading http:// or https://.

Example: http://www.awesome-ats.com

last-build-date

Type: string

Optional

Max characters: 100

The date this feed was last updated, in RFC3339 format with a space separator.

Example: 2020-11-06 18:47:08 +0000

job

Type: wrapper

Required

Each instance of this tag defines a job. See the full specification below.

Each feed XML file cannot contain more than 30,000 jobs. To publish more than 30,000 jobs, we recommend to split them into multiple feeds and maintain 1:1 mapping between the jobs and job_feed_id.

job tag

The <job> tag represents a singe job opening. The following sub-tags are valid within it.

NameDescription

title

Type: string

Required

Max characters: 1000

The job title. Plain text only.

Example: Cashier

date

Type: string

Required

Max characters: 1000

The date the job was posted, in RFC3339 format with a space separator.

Example: 2020-11-06 18:47:08 +0000

id

Type: string

Required

Max characters: 1000

A unique ID of your choosing that distinguishes this job from all other jobs you provide Facebook. Must be unique across all jobs and across all your XML feeds.

Example: unique11111

description

Type: string

Required

Max characters: 50000

The job description. Support basic HTML tags. Supported tags are

  • <br>
  • <p>
  • <ul> and <li>
  • <strong>
  • <i>
  • <h1> through <h6> heading tags

Newline characters are respected to start new lines. See sample XML below.

Example:

Greet customers with energy!

Arrange shopping carts, help customers with information.

company-id

Type: string

Required

Max characters: 1000

A unique ID of your choosing that distinguishes this hiring company from all other hiring companies you provide in your XML feeds.

Example: xyz123

Jobs for the same company may span multiple XML feeds as long as the company-id is the same, and all the job id values are unique.

All company- tags for the same company id must have identical values for each job. This includes company-name, company-url, company-full-address, company-url, company-facebook_url, and company-page-matching-approach.

company-name

Type: string

Required

Max characters: 1000

The name of the hiring company. Note this is usually not your company, but the company that is offering the job. Plain text only.

Example: Hiring Company, Ltd.

company-full-address

Type: string

Optional

Max characters: 1000

The full address of the hiring company. Note that the job itself may be at a different address, specified by <full-address>.

Example: 1 Hacker Way, Menlo Park, CA, 94025

company-url

Type: string

Required

Max characters: 1000

The URL of the hiring company's webpage, including leading http:// or https://. If the hiring company does not have a webpage, this may be the URL of their Facebook page, or be left blank.

Example: https://www.hiringcompany.com/

company-facebook-url

Type: string

Optional & Recommended

Max characters: 1000

The URL of the hiring company's Facebook page, including leading http:// or https://.

This URL will be used to match this job to a company's Facebook page, so the job will appear on that page.

If company-facebook-url is not provided, Facebook will make a best guess at associating this job with a page. If the job cannot be matched to a page, it will still be published and visible in the jobs browser.

Note that matching can be altered by the company-page-matching-approach tag.

Example: https://www.facebook.com/hiringcompany

company-page-matching-approach

Type: string

Optional

Determines whether or not jobs from this company will be matched to a Facebook page.

Supported values:

  • STANDARD: Standard matching.
  • NONE: Prevent the job from being matched to a page

STANDARD is the default.

This applies to all jobs from this company.

job-type

Type: string

Optional & Recommended

Supported values: FULL_TIME, PART_TIME, CONTRACT, INTERNSHIP, VOLUNTEER

FULL_TIME is the default.

remote-type

Type: string

Optional

Indicates that this job can be performed remotely.

Supported values:

  • FULLY_REMOTE: A job that can be performed entirely remotely from any location, and doesn't require any regular travel to an office or job site.
  • WFH_FLEXIBLE: A job for which employees have the flexibility to sometimes work remotely, but are still expected to report to a local office most of the time.
  • TEMPORARILY_REMOTE: A job that’s normally performed in a single location, such as an office or at a job site, but which is temporarily remote during the coronavirus (COVID-19) pandemic.

photo-url

Type: string

Optional

Max characters: 1000

Provide a photo for this job in the job's detail view in Facebook's Job Browser.

If the job is not matched to a Facebook page, no photo will be shown. Your app must be in Live mode to use this tag.

  • Include the leading http:// or https://. We do not support data:// URIs.
  • The image must be at least 400 pixels wide and 210 pixels tall, with a maximum file size of 4 MB.
  • We recommend an aspect ratio of 2.5:1 (width : height) for optimal cropping when displayed.
  • Supported image formats are jpg and png.

Example: http://www.hiringcompany.com/photo123.jpg

company-data-policy-url

Type: string

Optional & Recommended

Max characters: 1000

URL containing the data policy of the hiring company. A link to this URL will be shown when a user applies to this job. Include leading http:// or https://.

Example: https://www.hiringcompany.com/policy.php

full-address

Type: string

Optional & Recommended

Max characters: 1000

Full address of where the job is located. Note that the hiring company may have a different address, specified by <company-full-address>.

Example: 1 Hacker Way, Menlo Park, CA, 94025

house-number

Type: string

Optional

Max characters: 1000

House number where the job is located.

Example: 123

street-name

Type: string

Optional

Max characters: 1000

Name of the street where job is located.

Example: Hacker Way

city

Type: string

Optional

Max characters: 1000

City where the job is located.

Example: Menlo Park

region

Type: string

Optional

Max characters: 1000

Region where the job is located. In the United States this is the USPS two letter state abbreviation.

Example: CA

country

Type: string

Required

Max characters: 1000

2-letter ISO 3166-1 code for country where the job is located. A full English spelling of the country name may also work, but is not recommended.

Example: US

postal-code

Type: string

Optional

Max characters: 1000

Postal code for where the job is located. In the United States this is the zip code.

Example: 94025

salary

Type: number

Optional

Max characters: 1000

Salary of this job, without currency or separators. Digits and decimal point only.

Example: 150000

If the job is unpaid, then leave out all salary related tags.

salary-min

Type: number

Optional

Max characters: 1000

Minimum salary offered for this job, without currency or separators. Digits and decimal point only.

Example: 100000

Do not use if you provide the <salary> tag. If <salary-min> and <salary-max> are used, any value in <salary> will be ignored and the salary range will be displayed instead.

salary-max

Type: string

Required if salary-min used

Max characters: 1000

Maximum salary offered for this job, without currency or separators. Digits and decimal point only.

Example: 500000

salary-currency

Type: string

Required if salary or salary-min used

The 3 letter ISO 4217 code of the currency that the salary tags are denominated in.

Example: USD

salary-type

Type: string

Required if salary or salary-min used

The type of salary offered for this job.

Supported values: HOURLY, DAILY, WEEKLY, BIWEEKLY, MONTHLY, ANNUALLY, ONE-TIME

benefits

Type: string

Optional

The type of benefits provided by this job, separatd by comma.

Supported values: COMPUTER_BENEFITS, DENTAL_INSURANCE, DEPENDENT_CARE_ASSISTANCE, EMPLOYEE_DISCOUNTS, EMPLOYEE_HOUSING, EMPLOYEE_MEALS, FLEXIBLE_SPENDING_ACCOUNT, HEALTH_SAVINGS_ACCOUNT, LIFE_INSURANCE, MEDICAL_INSURANCE, ON_THE_JOB_TRAINING, PAID_FAMILY_AND_MEDICAL_LEAVE, PAID_TIME_OFF, RETIREMENT_ACCOUNT, RETIREMENT_ACCOUNT_COMPANY_MATCH, SIGNING_BONUS, VISION_INSURANCE

schedule-types

Type: string

Optional

The type of schedules used by this job, separatd by comma.

Supported values: DAY_SHIFT, FIXED_WEEKLY_SCHEDULE, FLEXIBLE_SCHEDULE, NIGHT_SHIFT, ROTATING_SCHEDULE, STANDARD_BUSINESS_SCHEDULE, SWING_SHIFT, WEEKEND_SCHEDULE

experience-required

Type: string

Optional

Whether the job requires prior experience.

Supported values: EXPERIENCE_NOT_REQUIRED, EXPERIENCE_REQUIRED

facebook-apply-data

Type: wrapper

Required

A wrapper tag that defines how applications to this job are handled. See the full specification below.

facebook-apply-data tag

NameDescription

application-callback-url

Type: string

Required

Max characters: 1000

A URL we will notify whenever your job receives an application. Include leading http:// or https://.

See Application Callback for the full documentation of this feature.

Example: https://yourdomain.com/callback

custom-questions-url

Type: string

Optional

Max characters: 1000

A URL endpoint containing questions you define in the JSON. Include leading http:// or https://.

See Custom Questions for the full documentation of this feature.

Example: https://yourdomain.com/custom-questions

form-config

Type: wrapper

Optional

This tag may contain tags to customize the job's application. See form-config-tag.

form-config tag

The contents of the form-config tag may be used to customize the application form that job seekers see for this job.

NameDescription

email-field

Type: wrapper

Optional

Determines whether the email field will be optional. Set to TRUE to make it optional.

Supported values:

  • <optional>FALSE</optional>
  • <optional>TRUE</optional>

FALSE is the default.

education-experience-field

Type: wrapper

Optional

Determines whether the education experience field will be optional. Set to TRUE to make it optional.

Supported values:

  • <optional>FALSE</optional>
  • <optional>TRUE</optional>

FALSE is the default.

work-experience-field

Type: wrapper

Optional

Determines whether the work experience field will be optional. Set to TRUE to make it optional.

Supported values:

  • <optional>FALSE</optional>
  • <optional>TRUE</optional>

FALSE is the default.

phone-number-field

Type: wrapper

Optional

Determines whether the phone number field will be optional. Set to TRUE to make it optional.

Supported values:

  • <optional>FALSE</optional>
  • <optional>TRUE</optional>

FALSE is the default.

resume-attachment-field

Type: wrapper

Optional

Determines whether the resume attachment field will be shown, and controls whether it is optional or required.

Resumes may be PDF files or photos from the mobile device. See Job Attachment Fields for information on how to retrieve resume attachments.

Supported values:

  • <optional>FALSE</optional>
  • <optional>TRUE</optional>
Resume attachments are currently only supported on mobile. If you set <optional> to FALSE, the job will only appear on mobile interfaces.
If the <optional> tag is not present, the resume attachment field will not be shown.

Feed XML Example

Below is a minimal valid job XML file. A longer file with with multiple jobs is available here.

<?xml version="1.0" encoding="utf-8"?>
<source>

<!-- Publisher and feed info -->
<publisher-name>Your ATS</publisher-name>
<publisher-url>http://www.yourdomain.com</publisher-url>
<last-build-date>2020-11-06 18:47:08 +0000</last-build-date>

<!-- Job tag. Repeat for each job opening. -->
<job>

<!-- Basic job info -->
<title><![CDATA[Mechanical Engineer]]></title>
<date><![CDATA[2020-11-06 18:47:08 +0000]]></date>
<id><![CDATA[unique11111]]></id>
<photo-url><![CDATA[http://www.hiringcompany.com/photo123.jpg]]></photo-url>
<description><![CDATA[Mechanical Engineer

  Help develop a perpetual motion machine. Great perks.
  ]]></description>
<job-type><![CDATA[FULL_TIME]]></job-type>

<!-- Company info -->
<company-name><![CDATA[Hiring Company, Ltd.]]></company-name>
<company-id><![CDATA[xyz123]]></company-id>
<company-full-address><![CDATA[1 Hacker Way, Menlo Park, CA, 94025]]></company-full-address>
<company-facebook-url>
    <![CDATA[https://www.facebook.com/hiringcompany]]>
</company-facebook-url>
<company-data-policy-url>
    <![CDATA[https://www.hiringcompany.com/policy.php]]>
</company-data-policy-url>
<company-url><![CDATA[https://hiringcompany.com]]></company-url>
<company-page-matching-approach><![CDATA[STANDARD]]></company-page-matching-approach>

<!-- Location -->
<full-address><![CDATA[1 Hacker Way, Menlo Park, CA, 94025]]></full-address>
<country><![CDATA[US]]></country>

<!-- Salary -->
<salary-min><![CDATA[100000]]></salary-min>
<salary-max><![CDATA[200000]]></salary-max>
<salary-currency><![CDATA[USD]]></salary-currency>
<salary-type><![CDATA[ANNUALLY]]></salary-type>

<!-- Integration configuration -->
<facebook-apply-data>
    <application-callback-url>
    <![CDATA[https://yourdomain.com/callback]]>
    </application-callback-url>
    <custom-questions-url>
    <![CDATA[https://yourdomain.com/custom-questions]]>
    </custom-questions-url>
    <form-config>
        <email-field>
            <optional>FALSE</optional>
        </email-field>
        <phone-number-field>
            <optional>FALSE</optional>
        </phone-number-field>
        <work-experience-field>
            <optional>FALSE</optional>
        </work-experience-field>
    </form-config>
</facebook-apply-data>

</job>

<!-- ...add more <job> tags for additional jobs -->

</source>
  

Validating your feed

To check your feed for basic syntax errors, you can validate it against the XSD schema. You will need a program that can validate XML. A popular choice is xmllint which is pre-installed on MacOS and many Linux distributions.

The jobs schema XSD file is located at https://fb.me/jobs_feed_validator.xsd

Example terminal command to validate a published feed at url https://fb.me/sample_job_feed_with_errors.xml:

curl -LsS "https://fb.me/sample_job_feed_with_errors.xml" > "/tmp/job_feed.xml" && \
curl -LsS "https://fb.me/jobs_feed_validator.xsd" > "/tmp/jobs_feed_validator.xsd" && \
xmllint --schema "/tmp/jobs_feed_validator.xsd" --noout "/tmp/job_feed.xml"

Example terminal command to validate a local file named example_job_feed.xml:

curl -LsS "https://fb.me/jobs_feed_validator.xsd" > "/tmp/jobs_feed_validator.xsd" && \
xmllint --schema "/tmp/jobs_feed_validator.xsd" --noout "example_job_feed.xml"

If everything looks good, this will output example_job_feed.xml validates.

Otherwise it will list validation problems along with the line number where the problem was found, similar to other linting programs. In the example below, an invalid URL for the <company-url> tag was found on line 459:

/tmp/job_feed.xml:459: element company-url: Schemas validity error : Element 'company-url': 'htpts://example.com' is not a valid value of the atomic type 'urlString'.