API Updates

Updated Monday, June 24, 2024

Added optional feedbackTemplate field to interviewers

feedbackTemplate can now be defined per interviewer. If a feedback template is not provided for an interviewer, it will default to the interview's feedback template.

The following endpoints were updated:

Interviews

Panels

Updated Monday, June 24, 2024

Removed 'prompt' query parameter from OAuth configuration steps

Including the prompt=consent query parameter in the user authorization URL will always request consent even if an app was already authorized with the exact same scopes. This blocked non-admin Microsoft365 SSO users from authorizing apps, even after Microsoft365 admin authorization.

Removed the requirement to include this query parameter such that consent is only requested when:

  • An app is newly authorized.
  • An app is re-authorized after consent was revoked.
  • An app is requesting new scopes.

Updated Monday, January 22, 2024

Added origin field to the /postings/:posting/apply post endpoint

The origin can be 'applied' or 'internal' to indicate whether application is internal application or external application. If not provided, origin will default to 'applied'.

Updated Thursday, March 16, 2023

Added accessRole filter to the /users get endpoint

Updated Tuesday, February 07, 2023

Added isAnonymized field to the /contacts get endpoint

Anonymous contacts cannot be updated and opportunities cannot be linked to an anonymous contact

Updated Tuesday, November 29, 2022

Add updatedAt to requisitions

The updatedAt property is now included in GET requisition payloads. The updatedAt property reflects a change to one of the following fields on the respective requisition: 'backfill', 'compensationBand', 'customFields', 'employmentStatus', 'headcountTotal', 'hiringManager', 'internalNotes', 'location', 'name', 'owner', 'requisitionCode', 'status', 'team', 'department', 'confidentiality', 'timeToFillStartAt', 'timeToFillEndAt'.

Updated Monday, October 3, 2022

Removed included_deleted filter from the list opportunities endpoint

The "include_deleted" query parameter on the list opportunities endpoint has been removed. Moving forward, please use the list deleted opportunities endpoint instead.

Updated Wednesday, September 28, 2022

Add Type to Archive Reason

Add archive reason type to the archive reasons endpoints.

Add support for filtering non-hired archive reasons

Type filter can now either be 'hired' or 'non-hired' for archive reasons endpoints.

Updated Wednesday, September 7, 2022

Add postingIds field to requisitions

Add the postingIds field of a requisition to the create requisitions endpoint & update requisitions endpoint.

PostingIds is now available as an optional array field. Adding a posting id to the postingIds array will link this requisition to the provided postings. If a postingIds array is not provided, then the field shall not be modified. Providing an empty array will clear all links to the requisition.

Add requisitionCodes field to postings

Add the requisitionCodes field of a posting to the create postings endpoint & update postings endpoint.

RequisitionCodes is now available as an optional array field. Adding an existing requisitionCode will link the requisition to the non-confidential posting. Confidential postings cannot be modified through the API. If a requisitionCodes field is not provided, then the field shall not be modified. Providing an empty array will clear all links to the posting.

Updated Friday, July 29, 2022

Add workplaceType field to Postings

Add the workplaceType field of a posting to the postings endpoints.

Updated Monday, July 19, 2022

Add timeToFillStartAt, timeToFillEndAt fields to Requisition

Add the timeToFillStartAt, timeToFillEndAt fields of a requisition to the requisitions endpoints.

Updated Thursday, July 14, 2022

OAuth is now available for EU Customers

Customers in the EU can now authorize OAuth integrations. Check out our OAuth documentation here to learn more.

Updated Monday, March 28, 2022

Add Status to Archive Reason

Add the status of an archive reason to the archive reasons endpoints.

Updated Wednesday, July 28, 2021

Update Note

Update an opportunity's note and any associated comments through the update note endpoint.

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

Updated Monday, April 19, 2021

Add a threaded comment to an existing note

  • create a threaded comment on the create a note endpoint by passing a note_id parameter
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

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

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.

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

Candidate

Updated Monday April 20, 2020

Additional endpoint to reactivate a user that has been previously deactivated

Updated Tuesday, March 10th, 2020

Additional Feedback and Profile Form Template Endpoints

This release contains the following:

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 the 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

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.

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:

Going forward, the contact field is the consistent unique identifier for an individual person in Lever, so all integrations should 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:

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 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 are 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.

Read more about postings here.

Updated Tuesday, October 10, 2017

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.

Updated Tuesday, August 1, 2017

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.

Read more about interviews here.

Updated Wednesday, April 12, 2017

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.

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.

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.

Updated Thursday, May 12

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.

Updated Friday, April 15

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.

Read more about the new filters.

Updated Monday, April 4, 2016

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.

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.

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 allows 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:

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!