postings-api

Lever Postings API

Table of contents

• Introduction
• Examples
• API methods
  • Sites
  • Get a list of job postings
  • Get a specific job posting
  • Apply to a job posting
  • iFrame resizing
• Third-party Libraries

Introduction

This repository contains documentation and example apps for the Lever Postings REST API. This API is designed to help you create a job site. If you need any features which are missing in this API or if you find any issues, please create a ticket or file an issue on this repository.

You do not need to use this API to get started with Lever job postings. All published job postings are also automatically viewable via your Lever-hosted job site (e.g. https://jobs.lever.co/leverdemo).

NOTE: When relevant, multiple URL examples are provided for the instances we support: global (default) and EU.

This API lets you:

• Get paginated job postings for your company
• Get job postings which match particular queries
• Get individual job postings (if you know their Posting ID)
• Programmatically apply to a job posting

The API does not:

• Let you do full-text searches over open jobs.
• Support cross-origin HTTP requests from sites outside of your company's domains/subdomains.
  • Note: The postings API does support cross-origin requests from your company's domains/subdomains, via CORS. For example, requests from yourcompanyname.com and subdomains like careers.yourcompanyname.com are allowed.
• Let you access internal job postings.
• Provide an iframe view for job detail pages or for application forms. You should either send applicants to the jobs site hosted at your Lever-hosted job site ([global][lever-job-site-global] / [EU][lever-job-site-eu]) or build your own detail view and application form on top of our JSON API.
• Let you specify custom success and error URLs for job postings.
• Expose custom questions built into your job postings.
• Add referral information.

If you are concerned about any features, please reach out to us and we'll prioritize the feature(s) you need.

Note that all job postings in the published state are publicly viewable. These jobs may be scraped by third parties. All other jobs are completely hidden from the jobs API.

Examples

These examples use the jQuery.ajax function to get lists of jobs and all use the global instance base url (i.e. https://api.lever.co/v0/postings/).

Simple list with two column layout

Displays all jobs alphabetically.

Two column layout with team filter

Display all jobs, and let the user filter by team.

Single column layout with cards

Displays all jobs alphabetically, with each job in a card.

Single column layout with cover image

Displays jobs in a single column, with a cover image on top.

Search and filtering example

Uses List.js to add search and filtering functionality similar to the Lever-hosted job site.

API Methods

The API is RESTful and all responses are HTML (for inlining) or serialized JSON.

All API methods are exposed under our postings base url ([global][postings-api-base-url-global] / [EU][postings-api-base-url-eu]).

The API is not available via unencrypted HTTP.

All URL parameters must be properly URL encoded.

The API will output HTML or JSON based on the Accept: header and the ?mode= query parameter. If both are provided, the query parameter has a higher precedence.

Sites

All job postings are name-spaced within a unique site name. Each company currently only has one site (usually your company name with no spaces). For example, Lever's job postings are under the site name lever, so they appear at [this API link][lever-postings-api-global] and [this job site link][lever-job-site-global] for those on the global instance and [this API link][lever-postings-api-eu] and [this job site link][lever-job-site-eu] for those on the EU instance.

Get a list of job postings

GET /v0/postings/SITE?skip=X&limit=Y

Examples: [global][leverdemo-postings-api-get-list-global] / [EU][leverdemo-postings-api-get-list-eu]

The API will return the data in three different formats:

• JSON: (recommended) Jobs list as raw JSON. See below for a list of supplied fields.
• HTML: The API returns jobs as HTML, which is designed to be inlined in your page. The jobs are sent as an HTML ul list contained inside a `` for easy styling.
• iframe: This returns HTML designed to be embedded in an iframe in your jobs page. The HTML will import a CSS stylesheet from a URL specified by the css= parameter. Like HTML mode, the jobs are listed in a ul inside a class='lever' div. To make the iframe size itself correctly (to remove scroll bars), please see the section on iframe resizing below.

You can use the HTTP Accept: application/json header or &mode=json GET parameter to specify the output mode. The URL parameter has higher precedence.

Fetch published job postings.

Query parameter	Description
mode	The rendering output mode. JSON, iframe or HTML.
skip	skip N from the start
limit	only return at most N results
location	Filter postings by location. You can specify multiple values and they are OR'ed together. Note: when specifying multiple values, this field is case sensitive! To specify multiple values, use the format ?location=Oakland&location=Boston.
commitment	Filter postings by commitment. You can specify multiple values and they are OR'ed together. Note: when specifying multiple values, this field is case sensitive! To specify multiple values, use the format ?commitment=Fulltime&commitment=Intern.
team	Filter postings by team. You can specify multiple values and they are OR'ed together. Note: when specifying multiple values, this field is case sensitive! To specify multiple values, use the format ?team=Product&team=Engineering.
department	Filter postings by department, if your company uses departments. You can specify multiple values and they are OR'ed together. Note: when specifying multiple values, this field is case sensitive! To specify multiple values, use the format ?department=Legal&department=Operations.
level	Filter postings by level.
group	May be one of location, commitment, or team. Returns results grouped by category
css	In iframe mode, the URL of a CSS stylesheet. Make sure the URL is also saved in the allowed list at Lever Job Site settings (https://hire.lever.co/settings/site).
resize	In iframe mode, the URL of an HTML page with a script for resizing the iframe (See usage below). Make sure the URL is also saved in the allowed list at Lever Job Site settings (https://hire.lever.co/settings/site).

In JSON mode, each job posting is a JSON object with the following fields:

Field	Description
id	Unique job posting ID
text	Job posting name
categories	Object with location, commitment, team, department, and allLocations.
Note: primary posting location is represented by location, and also appears in the allLocations array.
country	An ISO 3166-1 alpha-2 code for a country / territory (or null to indicate an unknown country). This is not filterable.
opening	Job description opening (as styled HTML).
openingPlain	Job description opening (as plaintext).
description	Combined job description opening and body (as styled HTML).
descriptionPlain	Combined job description opening and body (as plaintext).
descriptionBody	Job description body without opening (as styled HTML).
descriptionBodyPlain	Job description body without opening (as plaintext).
lists	Extra lists (such as requirements, benefits, etc.) from the job posting. This is a list of {text:NAME, content:"unstyled HTML of list elements"}
additional	Optional closing content for the job posting (as styled HTML). This may be an empty string.
additionalPlain	Optional closing content for the job posting (as plaintext). This may be an empty string.
hostedUrl	A URL which points to Lever's hosted job posting page. Examples: [global][leverdemo-job-site-posting-global] / [EU][leverdemo-job-site-posting-eu]
applyUrl	A URL which points to Lever's hosted application form to apply to the job posting. Examples: [global][leverdemo-job-site-posting-application-global] / [EU][leverdemo-job-site-posting-application-eu]
workplaceType	Describes the primary workplace environment for a job posting. May be one of unspecified, on-site, remote, or hybrid. Not filterable
salaryRange	Object with currency, interval, min, and max. This field is optional. In XML mode this field is parsed into a string.
salaryDescription	Optional description for the Salary range (as styled HTML).
salaryDescriptionPlain	Optional description for the Salary range (as plainText).

Get a specific job posting

GET /v0/postings/SITE/POSTING-ID

Examples: [global][leverdemo-postings-api-get-specific-posting-global] / [EU][leverdemo-postings-api-get-specific-posting-eu]

Get the named job posting by id. The fields which are available are the same as the fields exposed by the list API (above). This API only returns the named job posting in JSON format. (There is no iframe view or inline HTML view).

Apply to a job posting

WARNING: Application create requests are rate limited. Your team will need to properly handle 429 responses if you build a custom job application page. If you are unable to implement this logic, please consider directing to Lever's hosted application form instead of implementing a custom application form. See more below.

POST /v0/postings/SITE/POSTING-ID?key=APIKEY

You can add job applicants via a custom form on your site. Our API accepts candidate information in either JSON format or multipart form-data. However, our API only accepts resumes in multipart form data mode. Use a Content-Type header to instruct our server which format you're using. (Either application/json for JSON or application/x-www-form-urlencoded or multipart/form-data as appropriate).

The API is modeled off our hosted jobs form. Required fields and url fields can be customized per account. To determine what the job form looks like, look at any job application form for on your Lever-hosted job site ([global][job-site-global] / [EU][job-site-eu]) or visit your job site settings page ([global][lever-job