API Updates
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
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.
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'.
Added accessRole filter to the /users get endpoint
Added isAnonymized field to the /contacts get endpoint
Anonymous contacts cannot be updated and opportunities cannot be linked to an anonymous contact
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'.
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.
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.
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.
Add workplaceType field to Postings
Add the workplaceType field of a posting to the postings endpoints.
Add timeToFillStartAt, timeToFillEndAt fields to Requisition
Add the timeToFillStartAt, timeToFillEndAt fields of a requisition to the requisitions endpoints.
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.
Add Status to Archive Reason
Add the status of an archive reason to the archive reasons endpoints.
Update Note
Update an opportunity's note and any associated comments through the update note endpoint.
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.
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
Add a threaded comment to an existing note
- create a threaded comment on the create a note endpoint by passing a
note_idparameter
Updated Users endpoint to expose linkedContactIds
-
linkedContactIdsis 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.
Filter Postings by when they were updated
- filter the list all postings endpoint by when a posting was last updated
List users by external directory ID
- Users can be filtered by their external directory IDs
Update Contact
- contact information can now be updated using the update contact endpoint
Candidates moved to Deprecated
- Refer to Opportunities going forward
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.
Add opportunityId to interview webhooks
opportunityIdis included in the payload of interview webhooks.
Tag filtering functionality on Postings
- Added the ability to filter the List all postings endpoint with a
tagparameter.
Updated dropdown custom requisition fields functionality
- Added ability to create, update, or delete a dropdown field through the
requisition_fieldsendpoint - Added ability to append, update, or remove options on a dropdown without needing to replace the entire
requisition_fieldobject.
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.
Introducing new webhooks for Interviews
Added new webhooks for when interviews are created, updated, and deleted.
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
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.
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.
Additional endpoint to reactivate a user that has been previously deactivated
- Added the Reactivate a user endpoint.
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.
Expose the approval attribute on a requisition
Requisitions now include information about an approval. See the requisition documentation for more details.
Additional Endpoint to retrieve an offer file
- Added the Download offer file endpoint.
- Updated the List all offers endpoint to include the properties
sentDocumentandsignedDocument. These properties can be used to retrieve the respectivedownloadUrl.
Winter Release Changes
This release contains the following:
Deleted candidates can be shown in the List all candidates endpoint.
- Add
include_deletedas a query parameter to the List all candidates endpoint - A deleted candidate has the attributes
deletedByanddeletedAt, 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.
instructionscreatedAtstagefields
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 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
dedupeparameter asfalsein 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
emailparameter 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.
- Use this endpoint to apply a candidate to a published or unlisted posting (i.e., where the posting state is published or internal).
- 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.
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
- Added a field for
distributionChannels - Added a field for
hiringManager
- 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 are 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.
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 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.
- 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
reqCodethat contains the requisition code associated with a posting in Lever. - You can now filter the
candidateslist byarchived_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!