API Updates

Updated Wednesday, June 2, 2021

Added contact field to the /opportunities create endpoint

Linking an opportunity to an existing contact is now possible by providing the contact field which should contain the contact ID in the Create Opportunity request.

If contact is not specified in the request, old behavior will apply which is to attempt deduping a candidate by finding a match to the email provided in the Create Opportunity request.

If contact is specified and additional contact details are included in the request (emails, phones, tags, web links), these will be added to the existing candidate's contact information.

Updated Thursday, May 19, 2021

Added /opportunities/deleted endpoint

• An endpoint for retrieving a list of deleted opportunities has been added
• Deprecate the "include_deleted" query parameter on the list opportunities endpoint

Updated Tuesday, May 18, 2021

Updated Users endpoint to expose linkedContactIds

• linkedContactIds is now included in the payload of the Users endpoint. It is an array of contact IDs which helps identify all contacts associated with a User and can be used to control User access to any Opportunities linked to that User.

Updated Tuesday, March 2, 2021

Filter Postings by when they were updated

• filter the list all postings endpoint by when a posting was last updated

Updated Friday, February 5, 2021

List users by external directory ID

• Users can be filtered by their external directory IDs

Updated Wednesday, January 20, 2021

Update Contact

• contact information can now be updated using the update contact endpoint

Updated Wednesday, November 4, 2020

Candidates moved to Deprecated

• Refer to Opportunities going forward

Updated Friday, August 28, 2020

Update Candidates and Opportunities 'updatedAt' property

The updatedAt field will now update when any of the following fields are modified:

applications, archived, confidentiality, contact, dataProtection, emails, followers, headline, isAnonymized, lastAdvancedAt, lastInteractionAt, links, location, name, origin, owner, phones, snoozedUntil, sourcedBy, sources, stage, stageChanges, tags.

It will also update when any of the following fields on the expanded applications object are modified:

archived, candidateId, comments, company, customQuestions, email, links, name, opportunityId, phone, postingId, postingHiringManager, postingOwner, primarySource, requisitionForHire, secondarySources, type, user.

It will not update when any other fields or expanded values are modified.

Updated Wednesday, August 12, 2020

Add opportunityId to interview webhooks

• opportunityIdis included in the payload of interview webhooks.

Updated Tuesday, July 21, 2020

Tag filtering functionality on Postings

• Added the ability to filter the List all postings endpoint with a tag parameter.

Updated Thursday, July 9, 2020

Updated dropdown custom requisition fields functionality

• Added ability to create, update, or delete a dropdown field through the requisition_fields endpoint
• Added ability to append, update, or remove options on a dropdown without needing to replace the entire requisition_field object.

Updated Thursday, June 18, 2020

Custom requisition fields updates

The 'subfields' property will only be returned for custom requisition fields of type object. For fields of type dropdown, there will be a new 'options' property.

Visit the Requisition fields documentation for more details.

Updated Monday, June 15th, 2020

Introducing new webhooks for Interviews

Added new webhooks for when interviews are created, updated, and deleted.

Updated Wednesday, June 3rd, 2020

Updated Candidates and Opportunities to expose 'updatedAt' property

Updated candidates and opportunities to expose an 'updatedAt' property. This property is updated when the following fields are modified:

• Emails
• Stages
• Files
• Tags
• Sources
• Links
• Origins
• Resumes
• Name
• Archive status
• Organization summary

Updated Monday May 11, 2020

Custom questions will not be returned on posting endpoints

While a posting's custom questions used to be included as part of the response, it was always blank.

• Updated the Retrieve a single posting endpoint.
• Updated the List all postings endpoint.
• Updated the Create a posting endpoint.
• Updated the Update a posting endpoint.

In order to retrieve custom questions associated with a posting, use the Retrieve posting application questions endpoint.

Updated Thursday May 7, 2020

The following endpoints no longer require a perform_as query parameter

Opportunity

• Update stage endpoint.
• Update archive state endpoint.
• Update links endpoint.
• Update tags endpoint.
• Update sources endpoint.

Candidate

• Update stage endpoint.
• Update archive state endpoint.
• Update links endpoint.
• Update tags endpoint.
• Update sources endpoint.

Updated Monday April 20, 2020

Additional endpoint to reactivate a user that has been previously deactivated

• Added the Reactivate a user endpoint.

Updated Tuesday, March 10th, 2020

Additional Feedback and Profile Form Template Endpoints

This release contains the following:

• Added the Update a feedback template endpoint.
• Added the Update a profile form template endpoint.
• Added the Delete a feedback template endpoint.
• Added the Delete a profile form template endpoint.
• Added the Retrieve a feedback template endpoint.

Updated Friday, March 6th, 2020

Expose the approval attribute on a requisition

Requisitions now include information about an approval. See the requisition documentation for more details.

Updated Thursday, March 5th, 2020

Additional Endpoint to retrieve an offer file

• Added the Download offer file endpoint.
• Updated List all offers endpoint to include the properties sentDocument and signedDocument. These properties can be used to retrieve the respective downloadUrl.

Updated Monday, February 3rd, 2020

Winter Release Changes

This release contains the following:

Deleted candidates can be shown in the List all candidates endpoint.

• Add include_deleted as a query parameter to the List all candidates endpoint
• A deleted candidate has the attributes deletedBy and deletedAt, which show the ID of the user who deleted the candidate, and timestamp respectively.

Create endpoints for feedback and profile form templates

• Added the Create a feedback template endpoint.
• Added the Create a profile form template endpoint.

Additional attributes to feedback templates

Added the following attributes to feedback templates.

• instructions
• createdAt
• stage
• fields

This has updated the response of the List all feedback templates endpoint.

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.

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.

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

Add requisition when updating candidate archived state

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

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.

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

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.

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

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

Add data protection status to candidates endpoints

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

Add interview panel to interview

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

Add postings to interview

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

Add university posting form fields to custom questions for applications

University form fields are now available for applications and postings.

Add audit event for changing permission configurations for users

New audit event for changing permission configurations on users.

Add create-posting, and update-posting endpoints

Postings can now be created and updated through the api.

Read more about postings here.

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

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

Read more about users here.

Add audit event for linked profiles for users

New audit event for linking users to their hired profiles.

Add createdAt to interview

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

Read more about interviews here.

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.

Read more about creating candidates here.

Department support in postings

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

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.

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.

Read more about the new offers endpoint.

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

Read more about the new resumes.

Read more about the new files.

New audit events

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

Read more about the new audit events.

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.

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.

Read more about the new filters.

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.

Read more about the new stage changes attribute.

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.

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.

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.

• How do I push hired candidate information out of Lever into my HRIS system?
• How do I enable Namely integration?

New feedback form fields

Feedback forms now support a scorecard and code field type.

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.

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

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

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!