API Updates

Updated Monday, October 28, 2019

Add `contact` field to responses to Candidate endpoint requests, to payloads of webhook events, and as a filterable parameter to the List all candidates endpoint

To allow you to prepare for upcoming changes to Lever's data model, particularly regarding the Candidates endpoint, this release adds the contact field:

to responses to Candidate endpoint requests
to payloads of webhook events
as a filterable parameter to the List all candidates endpoint

Going forward, the contact field is the consistent unique identifier for an individual person in Lever, so all integrations should be be built and updated using the contact field as the unique person identifier and candidateId as a specific candidacy or opportunity moving through the pipeline.

Updated Wednesday, June 5, 2019

Sunset specification of `dedupe=false` for the Create a candidate endpoint

As announced on April 30, 2019, this release fully sunsets the ability to specify dedupe as false. All POST requests to /candidates will treat dedupe as true, regardless of whether this parameter is specified in the request.

Updated Tuesday, April 30, 2019

Deprecation of candidate endpoint features, with new replacement endpoints and suggested alternative methods

This release announces the deprecation of:

The ability to specify the dedupe parameter as false in the Create a candidate endpoint. Will be fully sunset effective June 5, 2019.
The use of the Create a candidate endpoint to update existing candidates' links, files, tags, or sources.
The ability to specify multiple posting UIDs in the Create a candidate endpoint.
The Add candidate postings endpoint.

Please see the linked documentation for preferred alternative methods.

In order to better support the direct updating of existing candidates using candidateId—as opposed to relying on the Create a candidate endpoint and the dedupe parameter to merge new information in—this release adds:

Update candidate links endpoints
Upload a single file endpoint
Delete a single file endpoint
A new email parameter for the List all candidates endpoint

Updated Tuesday, April 2, 2019

Add requisition when updating candidate archived state

You can now specify a requisition to hire a candidate against when archiving them as hired.

Updated March X, 2019 (ish)

Additional endpoints that support applying to a posting

Retrieve posting application questions

Retrieve all fields within an application form for a given posting (e.g., custom questions, URLs) with information about which fields are required or optional.

Apply to a posting

Use this endpoint to apply a candidate to a published or unlisted posting (i.e., where the posting state is published or internal).

Upload a file

This endpoint is designed to be used in conjunction with the Apply to a posting endpoint. If you need to include a file as part of an application, you must upload the file via this endpoint first.

If your API key grants access to the Apply to a posting endpoint, you will have automatically get access to this endpoint as well.

Updated December 6, 2018 (ish)

Various updates to the postings endpoints

Retrieve a single posting and List all postings

Added a field for distributionChannels (to help identify whether a job posting is displayed on your internal job site, external job site, or both)
Added a field for hiringManager
Query parameters for distributionChannels

Create a posting

Added a field for distributionChannels
Added a field for hiringManager

Update a posting

Added a field for distributionChannels

Updated Tuesday, June 26th, 2018

Add interviews write endpoints interview panel read & write endpoints

This release adds:

Interviews create, update, and delete endpoints.
Panel list, get, create, update, and delete endpoints.
Feedback Templates list endpoints.

Updated Monday, May 21st, 2018

Add date of deletion to profile forms, notes, and feedback endpoints

Profile forms, notes, and feedback will now return the deletion date as deletedAt.

Updated Tuesday, April 24th, 2018

Add data protection status to candidates endpoints

For users storing data protection status, the list_candidates and read_candidate endpoints now return dataProtection.

Updated Tuesday, March 6th, 2018

Add interview panel to interview

The interview panel associated with an interview is now available on interview endpoints.

Updated Monday, December 4th, 2017

Add postings to interview

The postings associated with an interview is now available on interview endpoints.

Updated Monday, December 4th, 2017

Add university posting form fields to custom questions for applications

University form fields are now available for applications and postings.

Updated Monday, November 20, 2017

Add audit event for changing permission configurations for users

New audit event for changing permission configurations on users.

Updated Thursday, September 7, 2017

Add create-posting, and update-posting endpoints

Postings can now be created and updated through the api.

Add create-user, update-user, and deactivate-user endpoints

Users can now be created, updated, and deactivated through the api.

Add audit event for linked profiles for users

New audit event for linking users to their hired profiles.

Updated Tuesday, June 6, 2017

Add createdAt to interview

The date and time an interview was created is now available on the interview related endpoints.

Allow for enhanced controls over candidate owner

When POSTing to /candidates, users will now be able to add an optional parameter perform_as_posting_owner, which will set the candidate owner to the owner of the first job posting in the postings array field.

Updated Monday, April 3, 2017

Department support in postings

For companies that use departments, the /postings endpoints now return categories.department and allow filtering by department.

Updated Tuesday, February 21, 2017

Audit event changes

The account.domain:changed and account.suite:changed audit events have been removed in favor of a combined account.suites:changed event to support accounts with multiple domains.

Updated Thursday, Jan 5 2017

New offers endpoint

There is now a new endpoint to retrieve all of the offers for a candidate: /candidates/:candidate/offers

This endpoint can be used in conjunction with our outgoing webhooks for hired candidates to integrate with an HRIS system.

New resumes and files endpoints

There are two new endpoints for candidates: resumes and files. These endpoints will allow you to get all resumes/files for a candidate, get a single resume or file for a candidate or download a single resume file (if it exists) or file.

New endpoints
`/candidates/:candidate/resumes`
`/candidates/:candidate/resumes/:resume`
`/candidates/:candidate/resumes/:resume/download`
`/candidates/:candidate/files`
`/candidates/:candidate/files/:file`
`/candidates/:candidate/files/:file/download`

New audit events

Several new audit events have been added for tracking events for your account including account activation, deactivation, domain name changes.

Interview timestamp now only available on interviews, not feedback

Interview timestamps used to be available in two places: on interviews themselves through the interviews endpoint and on any feedback forms associated with the interview. The interviewAt field is no longer available on feedback cards. (You can use the interview field from Feedback responses to look up the associated interview.)

In addition, the stage field on feedback cards has never been populated and has also been removed.

Updated Monday, April 11

Filter candidates by when they were last updated

There are two new filters available for the candidate list: updated_at_start and updated_at_end. These filters allow you to query for the most recently updated candidates. The candidate's updated timestamp is incremented whenever the candidate profile is updated. This is inclusive of updates to lastInteractionAt. Learn more about what last interaction is.

Access historical stage changes for candidates

Previously only the current stage of a candidate was available. Now you can access the entire stage change history.

Updated Wednesday, March 16, 2016

New API endpoints

We're stoked to announce that two new endpoints have been added to the API:

Requisitions for integrating requisitions with third-party tools, like an HRIS.
Audit events for tracking and querying security-related events in your Lever account. (Enterprise add-on)

Please note that if you have previously generated an API key with ALL permissions, you'll need to regenerate it to have access to Audit Events and Requisitions related endpoints. The key will not automatically be updated to include these new endpoints. Check your API key permissions from your account integration settings page.

Updated Friday, July 24, 2015

IMPORTANT: Sources and tags update

We are improving the way tags and sources are referenced. These updates will simplify filtering of the candidates and postings lists as well as remove the need for additional requests to map a tag/source ID to a text value.

The new filters and the new response body format (via the useNewTags query parameter) described in the current documentation are available.

On August 10, 2015, support for all old formats (old filters, old response bodies, old endpoints) described below will be disabled at 12:00pm Pacific time.

Before August 10th, we recommend following these four steps to use the improved API format:

Update your tag and source candidate list filters.

Deprecated format	New format
`GET /candidates?tag_id=49d67cab-31cd...`	`GET /candidates?tag=Engineering`
`GET /candidates?source_id=49d67cab-3...`	`GET /candidates?source=LinkedIn`

Add useNewTags=true to any candidate and posting requests.

Inside of candidate and posting response bodies, tags and sources will no longer be objects referenced by ID—they will be denormalized to strings. By adding the useNewTags query parameter, you will receive the new response body format.

You will also need to remove any expand=tags, expand=categories, and expand=sources parameters from requests to these endpoints.

Deprecated candidate format	New candidate format
`GET /candidates`	`GET /candidates?useNewTags=true`
`GET /candidates/:candidate`	`GET /candidates/:candidate?useNewTags=true`
`GET /candidates?expand=tags` `GET /candidates?expand=sources`	`GET /candidates?useNewTags=true` (notice we removed the expand parameter!)

Old format example

{
  id: '1b002ecf-d734-4a59-8387-9aae6f4074dff'
  tags: [
   '49d67cab-31cd-4965-b721-f7991…',
   '21d36cae-31ae-4965-b721-f7991…',
  ],
  sources: [
   '1a6a7715-2d20-4309-9475-2f27cac74…'
  ]
  …
}

New format example

{
  id: '3d848769-9c51-475f-bc71-68e36d6bce64'
  tags: ['hackathon', 'javascript'],
  sources: ['LinkedIn']
  …
}

Deprecated posting format	New posting format
`GET /postings`	`GET /postings?useNewTags=true`
`GET /postings/:posting`	`GET /postings/:posting?useNewTags=true`
`GET /postings?expand=tags` `GET /postings?expand=sources` `GET /postings?expand=categories`	`GET /postings?useNewTags=true` (notice we removed the expand parameter!)

Old format example

{
  id: '1a6a7715-2d20-4309-9475-2f27cac74afa',
  tags: [
   '49d67cab-31cd-4965-b721-f7991…',
   '21d36cae-31ae-4965-b721-a5991…',
  ],
  categories: {
   location: '19d67cab-31cd-4965-b721-f7991…'
    commitment: '29d67cab-31cd-4965-b721-f7…'
    team: '49d57cab-31cd-4965-b721-f7991…'
    level:'59d67cab-31cd-4965-b721-f7991…'
  }
  …
}

New format example

{
  id: '37c2fb0d-03ef-4c7d-a6b0-cac02488f53b',
  tags: ['hackathon', 'javascript'],
  categories: {
   location: 'San Francisco'
    commitment: 'Full-time'
    team: 'Engineering'
    level:'Senior'
  }
  …
}

Endpoints for fetching tags by ID will be removed

Deprecated format	New format
`GET /tags/:tag`	REMOVED
`GET /sources/:source`	REMOVED

Tags/Sources endpoints will no longer have `id` or `createdAt` fields

Old format example

{
  id: '1a6a7715-2d20-4309-9475-2f27cac74afa',
  text: 'Javascript',
  count: 34,
  createdAt: 1438648045853
}

New format example

{
  text: 'Javascript',
  count: 34,
}

New endpoints for sourcing integrations

We are excited to introduce several new endpoints that will enable external tools to import new candidates into Lever.

Create new candidates in Lever. We're giving you complete control to specify custom candidate tags and sources, pipeline stage, and job posting.
Receive updates when a candidate is archived from your active pipeline with Lever's new candidate archive status webhook.
Enable a two-way archive status sync using both Lever's webhooks and endpoint to update a candidate's archive status.
Two-way candidate stage sync. Lever's webhooks allow you to update a candidate's stage in Lever.
Add or remove tags and sources on a candidate profile.
Add job postings to a candidate profile.

Updated Friday, May 15, 2015

Introducing Lever webhooks

We are excited to introduce new custom webhooks to enable integrations: candidate hired event webhook and a candidate stage change webhook. Lever's candidate hired webhook allow you to seamlessly move candidates that are hired in Lever into your HRIS, minimizing time spent on manual data entry. Check out our help articles to get started.

Updated Wednesday, April 22, 2015

New feedback form fields

Feedback forms now support a scorecard and code field type.

Updated Wednesday, April 22, 2015

New candidate field: origin

Finally a way to really know how a candidate entered the system! All it takes is a string and you will be able to see whether a candidate was sourced, applied, referred, manually added and more. Head on over to the documentation to give it a try.

Updated Wednesday, March 25, 2015

Requisition code added to Postings and a new filter.

We have two exciting updates:

A new field was added to postings called reqCode that contains the requisition code associated with a posting in Lever.
You can now filter the candidates list by archived_posting_id

Updated Monday, February 9, 2015

Lever API Launch

We’re pleased to announce that the first public version of the Lever API is live!

The Lever API will give you the ability to export candidate data or subsets of this data filtered by fields such as job posting, tag, source, or pipeline stage. At the moment, the API is read-only, but you'll soon be able to create candidates through the API as well.

Here's what you need to get started:

Generate an API key at https://hire.lever.co/settings/integrations
Note that you must be a Super Admin in Lever in order to do so
Check out our documentation at https://hire.lever.co/developer/documentation
Use the API endpoint at https://api.lever.co/v1

Thanks to all our beta users! If you've already been using the API, you might be interested in these new features:

Retrieve interview events and feedback for a candidate
Get referrals made for a candidate (both those created manually and via application)
Retrieve profile forms on a candidate, including offer information
Retrieve notes on a candidate
Retrieve custom questions on applications
Create new tags for your account

Updated Monday, January 12, 2015

Lever API beta launch

We’re thrilled to announce the beta launch of Lever’s API! You now have effortless access to every speck of data in your hiring process. Our Data API gives you the ability to export candidate data or subsets of this data filtered by fields such as job posting, tag, source, or pipeline stage.

For our first beta release, the API is read-only, but you'll soon be able to create candidates through the API as well.

Stay tuned for many more exciting updates -- including an official release -- coming soon!

API Updates

Add contact field to responses to Candidate endpoint requests, to payloads of webhook events, and as a filterable parameter to the List all candidates endpoint

Sunset specification of dedupe=false for the Create a candidate endpoint

Deprecation of candidate endpoint features, with new replacement endpoints and suggested alternative methods

Add requisition when updating candidate archived state

Additional endpoints that support applying to a posting

Various updates to the postings endpoints

Add interviews write endpoints interview panel read & write endpoints

Add date of deletion to profile forms, notes, and feedback endpoints

Add data protection status to candidates endpoints

Add interview panel to interview

Add postings to interview

Add university posting form fields to custom questions for applications

Add audit event for changing permission configurations for users

Add create-posting, and update-posting endpoints

Add create-user, update-user, and deactivate-user endpoints

Add audit event for linked profiles for users

Add createdAt to interview

Allow for enhanced controls over candidate owner

Department support in postings

Audit event changes

New offers endpoint

New resumes and files endpoints

New audit events

Interview timestamp now only available on interviews, not feedback

Filter candidates by when they were last updated

Access historical stage changes for candidates

New API endpoints

IMPORTANT: Sources and tags update

Update your tag and source candidate list filters.

Add useNewTags=true to any candidate and posting requests.

Old format example

New format example

Old format example

New format example

Endpoints for fetching tags by ID will be removed

Tags/Sources endpoints will no longer have id or createdAt fields

Old format example

New format example

New endpoints for sourcing integrations

Introducing Lever webhooks

New feedback form fields

New candidate field: origin

Requisition code added to Postings and a new filter.

Lever API Launch

Lever API beta launch

Add `contact` field to responses to Candidate endpoint requests, to payloads of webhook events, and as a filterable parameter to the List all candidates endpoint

Sunset specification of `dedupe=false` for the Create a candidate endpoint

Tags/Sources endpoints will no longer have `id` or `createdAt` fields