# Lever
Connecting Lever gives SureCloud read access to your Lever account's opportunities, contacts, offers, and user data. SureCloud uses Lever as a source of recruiting and pre-employment evidence — tracking candidates who have received and accepted offers, cross-referencing offer acceptance dates and start dates against background check completion records, and collecting new hire data to support joiner controls. SureCloud also reads user access within the Lever platform to verify that recruiter and hiring manager permissions are appropriately scoped. This provides evidence that your hiring pipeline records are complete and that pre-employment requirements are being met before new employees start.
{% hint style="info" %}
SureCloud connects to Lever using OAuth 2.0. Lever supports OAuth 2.0 for partner integrations via the Lever Partner Programme. API key authentication is also available for Lever Enterprise customers using the Data API directly.
{% endhint %}
## Authentication and setup
{% tabs %}
{% tab title="OAuth 2.0 (recommended)" %}
{% stepper %}
{% step %}
#### Initiate the connection in SureCloud
In SureCloud, navigate to **Integrations → Lever → Connect**. SureCloud redirects you to Lever's OAuth authorisation page.
{% endstep %}
{% step %}
#### Authorise SureCloud in Lever
Review the requested permissions and click **Accept**. The OAuth application is pre-registered by SureCloud.
SureCloud requests the following OAuth scopes:
| Scope | Purpose |
| -------------------------- | ----------------------------------------------------------------- |
| `opportunities:read:admin` | Read all opportunity (candidate) records and their pipeline stage |
| `offers:read:admin` | Read offer records including acceptance status and start dates |
| `users:read:admin` | Read Lever user accounts and their access role |
| `contacts:read:admin` | Read contact records linked to opportunities |
| `tags:read` | Read custom tags applied to opportunities for filtering |
{% hint style="warning" %}
The authorising account must hold the **Super Admin** role in Lever to grant `admin`-level scopes. Non-admin accounts can only read data for opportunities they are assigned to as an interviewer or owner.
{% endhint %}
{% endstep %}
{% step %}
#### Confirm the connected account
After authorisation, SureCloud displays the connected Lever account name and the authorising user. Confirm these match and click **Save Connection**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="API Key (Lever Enterprise)" %}
{% stepper %}
{% step %}
#### Generate a Lever Data API key
In Lever, navigate to **Settings → Integrations and API → API Credentials → Generate New Key**.
* **Name**: `SureCloud CCM`
* **Role**: **Read only**
Copy the API key value immediately.
{% hint style="warning" %}
Lever API keys do not expire automatically. Rotate this key every 90 days and update it in **SureCloud → Integrations → Lever → Edit Connection**.
{% endhint %}
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → Lever → Connect (API Key)** and provide:
* **API key**
Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
## Endpoints
| API Call | Use Case |
| ----------------------------------- | ----------------------------------------------------------------------------- |
| `GET /v1/opportunities` | Enumerate all opportunities with current pipeline stage and owner |
| `GET /v1/opportunities/{id}` | Read full opportunity record including tags, source, and archived reason |
| `GET /v1/opportunities/{id}/offers` | Read offer records per opportunity; retrieve acceptance status and start date |
| `GET /v1/offers` | Enumerate all offers across the account with status and signed date |
| `GET /v1/contacts/{id}` | Read contact profile linked to an opportunity |
| `GET /v1/users` | Enumerate Lever users with their access role and active status |
| `GET /v1/stages` | List pipeline stage definitions for context on opportunity progression |
| `GET /v1/tags` | List tag definitions used for opportunity categorisation |
| `GET /v1/archive_reasons` | Read archive reason definitions for declined or withdrawn candidates |
## Pagination
The Lever API uses cursor-based pagination via a `next` field in the response body. When more results are available, the response includes a `hasNext: true` flag and a `next` cursor string. SureCloud passes the cursor as the `offset` query parameter in successive requests until `hasNext` is `false`.
```json
{
"data": [
{
"id": "opportunity-uuid-abc123",
"name": "Alice Nguyen",
"stage": { "id": "stage-uuid", "text": "Offer" },
"offers": [ { "status": "signed", "signedAt": 1748822400000 } ]
}
],
"hasNext": true,
"next": "opportunity-uuid-xyz789"
}
```
SureCloud requests up to 100 records per page using the `limit=100` query parameter.
## Required permissions
For OAuth 2.0, the authorising account must hold the **Super Admin** role in Lever to grant `admin`-level read scopes. Without Super Admin, scopes are restricted to data the user personally owns or is assigned to, which limits SureCloud to a partial view.
For API key access (Lever Enterprise), the **Read only** key type provides access to all Lever data endpoints without write capability.
## Polling frequency
| Data type | Collection interval |
| -------------------------------- | ------------------- |
| Opportunities and pipeline stage | 24 hours |
| Offer records and start dates | 24 hours |
| User and role inventory | 24 hours |
| Archive and decline records | 24 hours |
## Troubleshooting
Offer records are not appearing for candidates who have accepted offers
Offer records in Lever are linked to opportunities via the `/opportunities/{id}/offers` endpoint. If offers are missing, the `offers:read:admin` scope may not have been granted during the OAuth flow, or the API key may not have access to the offers endpoints.
Re-connect the integration via **SureCloud → Integrations → Lever → Reconnect** and confirm the authorising account holds the Super Admin role so all `admin` scopes can be granted.
Only some opportunities are appearing — candidates from certain teams are missing
If the OAuth connection was authorised by a non-Super Admin account, Lever restricts API responses to opportunities the authorising user is directly involved with as an interviewer or opportunity owner. This produces a partial dataset.
Re-connect using a **Super Admin** account to grant access to all opportunities across the account.
User access roles are not appearing for some Lever users
User role data is returned from the `/v1/users` endpoint. If roles are missing for specific users, those users may be in a `pending` invitation state (not yet activated) or may have been deactivated. SureCloud includes pending and deactivated users in the inventory alongside active users and flags their status accordingly.
If the role field is present but empty, the user may have a custom role. Confirm role definitions in **Lever → Settings → Team → Roles**.
OAuth token is returning errors after a Super Admin account change
If the Lever Super Admin account that authorised the SureCloud connection is deactivated or demoted to a lower role, the OAuth refresh token may lose its scope grants.
Re-connect the integration using a current active Super Admin account via **SureCloud → Integrations → Lever → Reconnect**.
Lever API reference
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/lever.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.