|
|
The information in this article is meant for those that have developed a custom integration using Lever's API. |
We are excited to announce that Lever is enhancing our unified candidate profile by adding an opportunity timeline view! This update will enable recruiting teams to manage candidates for multiple opportunities at the same time, while still providing a holistic view of all candidate data in a single unified profile.
Changes to Lever's data model
To support these changes, the current "Candidates" in your Lever account will be migrated to a new data model where each Candidate will be represented by one or many Opportunities. On Lever's new data model, a "Contact" will have independent Opportunities for each of their Applications. This means that any current Candidate with multiple Applications will be split into several candidateIds, and represented as Opportunities and opportunityIds via new Opportunities endpoints.
Candidates enter your pipeline for a new Opportunity by:
- Applying to a posting on your jobs site,
- Being added by an external recruiting agency,
- Being referred by an employee,
- Being manually added by a Lever user, or
- Being sourced from an online profile
Each Opportunity can have their own notes, feedback, interview schedules, and additional forms. Opportunities exit your pipeline by being archived for one of two reasons: (1) The candidate was rejected for the opportunity, or (2) The candidate was hired for the opportunity.
A "Contact" is an object that our application uses internally to identify an individual person and their personal or contact information, even though they may have multiple opportunities. From this API, the "Contact" is exposed via the contact field, which returns the unique ID for a Contact across your account. Contact information will be shared and consistent across an individual person's opportunities, and will continue to be aggregated onto individual opportunities in the responses to all GET and POST requests to /opportunities.
What does this mean for my integration?
Because these changes may affect custom built integrations with our API, we’ve prepared guides, linked below, that detail any changes or preparations that should be completed before your account is migrated to our new data model.
Each of the articles linked below refers to new API attributes detailed in the table below. Please review this terminology before continuing to the suggested integration updates.
| pre-Opportunities release | post-migration and release | |
| contactId | UID for a candidate in Lever. contactId and candidateId are 1:1 as candidates only have a single Lever profile. | UID for a candidate in Lever. A candidate has a single contactId that links all of their opportunityId(s). |
| opportunityId | N/A |
UID for a candidate’s opportunity in Lever. A candidate may have multiple opportunityIds, all linked by a unique contactId. |
| candidateId | A candidate in Lever has a single profile and candidateId. |
A candidate in Lever may have multiple candidateIds, all linked by a unique contactId. |
To better enable development with our new data model, we have added new Opportunities endpoints as a replacement to the now deprecated Candidates endpoints. For any given opportunity, the candidateId you would use for a request to a Candidates endpoint can be used as the opportunityId in a request to the corresponding Opportunities endpoint.
Going forward, the contact field is the 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 opportunityId as a specific opportunity or candidacy moving through the pipeline.
|
|
The Candidate endpoints are deprecated but maintained for backwards compatibility. |
To learn more about the suggested updates by type of integration, please review the following articles:
- Updating your sourcing integration for the Opportunities data model
- Updating your background check integration for the Opportunities data model
- Updating your assessment integration for the Opportunities data model
- Updating your HRIS integration for the Opportunities data model
- Updating your data warehouse integration for the Opportunities data model
- Updating your scheduling integration for the Opportunities data model
- Updating your auto-categorization integration for the Opportunities data model
- Updating your tagging integration for the Opportunities data model