A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Lever API is how an app or AI agent works with a Lever recruiting account: listing and creating opportunities, submitting applications to postings, scheduling interviews, and adding notes on a candidate. Access is granted through an API key that reaches the whole account, or an OAuth token carrying granular scopes that set which resources a call can read or write. A state change, like a new application or a candidate moving stage, can be pushed to a registered endpoint.
How an app or AI agent connects to Lever determines what it can reach. There is a route for making calls and a route for receiving events, and each is governed by the API key or the OAuth token behind it and the permissions that credential carries.
The REST API answers at https://api.lever.co/v1, returns JSON, and pages through lists with an opaque offset token. A call authenticates with an API key over HTTP Basic auth or with an OAuth 2.0 access token. List responses carry hasNext and next fields for paging.
Lever POSTs a JSON payload to an HTTPS endpoint when a subscribed event fires, such as a new application or a candidate stage change. The payload carries a triggeredAt timestamp, the event type, a data object, and a signature. The receiver verifies the signature by computing an HMAC-SHA256 over the concatenated token and triggeredAt values using the webhook's signature token.
An API key is sent as the username in HTTP Basic auth, with the password left blank. A key grants account-wide access rather than carrying granular scopes, so it is not least-privilege. Keys are created in the account's Integrations settings.
OAuth 2.0 uses the authorization-code flow at auth.lever.co, with granular scopes like opportunities:read:admin and postings:write:admin. A write scope includes the matching read access, and offline_access enables refresh tokens. Access tokens expire after one hour, and refresh tokens rotate on each exchange. Most use cases need 5 to 8 scopes, with a maximum of 20.
The Lever API is split into areas an agent can act on, like opportunities, postings, applications, interviews, offers, and notes. Each area has its own methods, and writes in some areas move a candidate through hiring or change a live job posting.
List, read, and create opportunities, the records that represent a candidate's pursuit of a job, and update an opportunity's stage.
List and read the applications on an opportunity, and submit a new application to a posting.
List and read job postings, and create or update a posting.
List, read, create, update, and delete the interviews scheduled on an opportunity.
List the offers on an opportunity and download a generated offer file.
List, read, create, update, and delete interview feedback forms on an opportunity.
List, read, create, and delete the notes recorded on an opportunity.
List, read, and download the resumes attached to an opportunity.
List and read the pipeline stages and the archive reasons configured in an account.
List and read users, create a user, and deactivate or reactivate one.
List webhooks and create a new one to subscribe to account events.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
Opportunities (candidates)List, read, and create opportunities, the records that represent a candidate's pursuit of a job, and update an opportunity's stage.4 | ||||||
| GET | /opportunities | List all opportunities (candidate pursuits of a job) in the account. | read | opportunities:read:admin | Current | |
Read-only. The opportunities endpoints replaced the deprecated candidates endpoints. With an API key, Basic auth grants account-wide access instead of a scope. Acts onopportunity Permission (capability) opportunities:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /opportunities/:opportunity | Retrieve a single opportunity by id. | read | opportunities:read:admin | Current | |
Read-only. Acts onopportunity Permission (capability) opportunities:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /opportunities | Create an opportunity, optionally creating a candidate and linking the opportunity to postings. | write | opportunities:write:admin | Current | |
A write scope includes the matching read access. A perform_as query parameter records which user the action is taken on behalf of. Acts onopportunity Permission (capability) opportunities:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /opportunities/:opportunity/stage | Update the pipeline stage of an opportunity, moving the candidate forward or back. | write | opportunities:write:admin | Current | |
Advancing the stage is the action a candidateStageChange webhook reports. Acts onopportunity Permission (capability) opportunities:write:adminVersionAvailable since the API’s base version Webhook event candidateStageChangeRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ApplicationsList and read the applications on an opportunity, and submit a new application to a posting.3 | ||||||
| GET | /opportunities/:opportunity/applications | List all applications on an opportunity. | read | applications:read:admin | Current | |
Read-only. Acts onapplication Permission (capability) applications:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /opportunities/:opportunity/applications/:application | Retrieve a single application on an opportunity. | read | applications:read:admin | Current | |
Read-only. Acts onapplication Permission (capability) applications:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /postings/:posting/apply | Submit an application to a posting, creating the candidate and application. | write | applications:write:admin | Current | |
Application POST requests are limited to 2 per second, tighter than the 10 per second account limit. Creating an application fires the applicationCreated webhook. Acts onapplication Permission (capability) applications:write:adminVersionAvailable since the API’s base version Webhook event applicationCreatedRate limit2 requests per second SourceOfficial documentation ↗ | ||||||
Postings (jobs)List and read job postings, and create or update a posting.4 | ||||||
| GET | /postings | List all job postings in the account. | read | postings:read:admin | Current | |
Read-only. Acts onposting Permission (capability) postings:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /postings/:posting | Retrieve a single job posting by id. | read | postings:read:admin | Current | |
Read-only. Acts onposting Permission (capability) postings:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /postings | Create a job posting. | write | postings:write:admin | Current | |
A write scope includes the matching read access. Acts onposting Permission (capability) postings:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /postings/:posting | Update a job posting. | write | postings:write:admin | Current | |
A write here changes a live job posting. Acts onposting Permission (capability) postings:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
InterviewsList, read, create, update, and delete the interviews scheduled on an opportunity.4 | ||||||
| GET | /opportunities/:opportunity/interviews | List all interviews scheduled on an opportunity. | read | interviews:read:admin | Current | |
Read-only. Acts oninterview Permission (capability) interviews:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /opportunities/:opportunity/interviews | Create an interview on an opportunity. | write | interviews:write:admin | Current | |
Creating an interview fires the interviewCreated webhook. Acts oninterview Permission (capability) interviews:write:adminVersionAvailable since the API’s base version Webhook event interviewCreatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /opportunities/:opportunity/interviews/:interview | Update an interview on an opportunity. | write | interviews:write:admin | Current | |
Updating an interview fires the interviewUpdated webhook. Acts oninterview Permission (capability) interviews:write:adminVersionAvailable since the API’s base version Webhook event interviewUpdatedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /opportunities/:opportunity/interviews/:interview | Delete an interview on an opportunity. | write | interviews:write:admin | Current | |
Deleting an interview fires the interviewDeleted webhook. Acts oninterview Permission (capability) interviews:write:adminVersionAvailable since the API’s base version Webhook event interviewDeletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OffersList the offers on an opportunity and download a generated offer file.1 | ||||||
| GET | /opportunities/:opportunity/offers | List the offers extended on an opportunity. | read | offers:read:admin | Current | |
Read-only; offers contain compensation details. Acts onoffer Permission (capability) offers:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
FeedbackList, read, create, update, and delete interview feedback forms on an opportunity.2 | ||||||
| GET | /opportunities/:opportunity/feedback | List the interview feedback forms on an opportunity. | read | feedback:read:admin | Current | |
Read-only. Assignment and share feedback types are included alongside interview feedback. Acts onfeedback Permission (capability) feedback:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /opportunities/:opportunity/feedback | Create an interview feedback form on an opportunity. | write | feedback:write:admin | Current | |
A write scope includes the matching read access. Acts onfeedback Permission (capability) feedback:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
NotesList, read, create, and delete the notes recorded on an opportunity.3 | ||||||
| GET | /opportunities/:opportunity/notes | List the notes recorded on an opportunity. | read | opportunities:read:admin | Current | |
Read-only. Notes are accessed through the opportunities scope. Acts onnote Permission (capability) opportunities:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /opportunities/:opportunity/notes | Create a note on an opportunity. | write | opportunities:write:admin | Current | |
Notes are governed by the opportunities write scope. Acts onnote Permission (capability) opportunities:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /opportunities/:opportunity/notes/:note | Delete a note from an opportunity. | write | opportunities:write:admin | Current | |
Irreversible removal of a note. Acts onnote Permission (capability) opportunities:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ResumesList, read, and download the resumes attached to an opportunity.2 | ||||||
| GET | /opportunities/:opportunity/resumes | List the resumes attached to an opportunity. | read | resumes:read:admin | Current | |
Read-only; resumes contain candidate personal data. Acts onresume Permission (capability) resumes:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /opportunities/:opportunity/resumes/:resume/download | Download a resume file attached to an opportunity. | read | resumes:read:admin | Current | |
Returns the raw resume file. Acts onresume Permission (capability) resumes:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Stages & archive reasonsList and read the pipeline stages and the archive reasons configured in an account.2 | ||||||
| GET | /stages | List the pipeline stages configured in the account. | read | stages:read:admin | Current | |
Read-only. Acts onstage Permission (capability) stages:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /archive_reasons | List the archive reasons configured in the account. | read | archive_reasons:read:admin | Current | |
Read-only. Acts onarchive_reason Permission (capability) archive_reasons:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
UsersList and read users, create a user, and deactivate or reactivate one.3 | ||||||
| GET | /users | List the users in the account. | read | users:read:admin | Current | |
Read-only. Acts onuser Permission (capability) users:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users | Create a user in the account. | write | users:write:admin | Current | |
A write here changes who can access the Lever account. Acts onuser Permission (capability) users:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /users/:user/deactivate | Deactivate a user, removing their access to the account. | write | users:write:admin | Current | |
Reversible with the reactivate endpoint. Acts onuser Permission (capability) users:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksList webhooks and create a new one to subscribe to account events.2 | ||||||
| GET | /webhooks | List the webhooks configured in the account. | read | webhooks:read:admin | Current | |
Read-only. Acts onwebhook Permission (capability) webhooks:read:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /webhooks | Create a webhook subscription for account events. | write | webhooks:write:admin | Current | |
A write here changes which events are pushed out of the account. Acts onwebhook Permission (capability) webhooks:write:adminVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Lever can notify an app when something happens in an account, like a new application arriving or a candidate moving to a new stage. It sends a JSON payload describing what changed, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
applicationCreated | Fires when a new application is created on an opportunity, for example through a posting's apply form. | /postings/:posting/apply |
candidateStageChange | Fires when a candidate is moved to a different pipeline stage. | /opportunities/:opportunity/stage |
candidateArchiveChange | Fires when a candidate is archived or unarchived, optionally filtered by archive reason. | In-app only |
candidateHired | Fires when a candidate is marked hired. | In-app only |
candidateDeleted | Fires when a candidate is deleted from the account. | In-app only |
interviewCreated | Fires when an interview is scheduled on an opportunity. | /opportunities/:opportunity/interviews |
interviewUpdated | Fires when a scheduled interview is updated. | /opportunities/:opportunity/interviews/:interview |
interviewDeleted | Fires when a scheduled interview is deleted. | /opportunities/:opportunity/interviews/:interview |
Lever limits how fast an app can call, by a request rate measured per second per API key, with a tighter limit on submitting applications.
Lever meters requests per API key at a steady 10 requests per second, with bursts up to 20 per second when capacity allows. Submitting an application is held tighter, to 2 requests per second. Going over returns HTTP 429, where the response should be met with exponential backoff. Lever notes the limit can change without warning.
List endpoints are paginated with limit and offset. The limit sets the page size, defaulting to 100 and ranging from 1 to 100, and offset takes an opaque token from the previous response rather than a numeric index. The response includes a hasNext boolean and a next token, and pages are followed until hasNext is false.
A list endpoint returns at most 100 records per page, the maximum value of limit. Uploaded files support formats including pdf, doc, docx, txt, jpg, and png; image files are stored but not parsed.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | A parameter is missing or malformed. The response body carries a code and a human-readable message. | Read the message, correct the parameters, and resend. The request is not retryable as-is. |
| 401 | Unauthorized | Authentication is missing or invalid, for example a wrong API key or an expired OAuth access token. | Confirm the API key, or refresh the OAuth access token using the refresh token, then resend. |
| 403 | Forbidden | The credential is valid but lacks permission for the request, for example an OAuth token without the required scope. | Grant the missing scope on the OAuth token, then resend. |
| 404 | ResourceNotFound | The requested resource does not exist or is not visible to the credential. | Verify the resource id and that the credential has access to it. |
| 429 | Too Many Requests | The request rate exceeded the per-key limit of 10 requests per second, or the 2 per second limit on submitting applications. | Back off and retry with exponential backoff, and smooth the request rate. |
| 500 | Server Error | An error on Lever's side. | Retry with backoff, and contact Lever support if it persists. |
| 503 | Service Unavailable | The API is temporarily unavailable, for example during maintenance. | Wait and retry with backoff. |
Lever runs a single continuously updated version of its API, with no dated version to pin, and ships changes through dated entries on its developer updates page.
Lever runs one continuously updated version of its API under /v1, with no dated version to pin. Notable changes ship as dated entries on the developer updates page, and recent additions have been additive, including endpoints for retrieving deleted records and new metadata fields on applications.
Earlier dated updates from the developer updates page.
There is no version to pin; track the developer updates page for changes.
Lever API updates ↗Bollard AI sits between a team's AI agents and Lever. Grant each agent exactly the access it needs, read or write, resource by resource, and every call is checked and logged.