You may have an integration that streamlines the screening process by categorizing candidates based on their responses to application questions. You’ll want to make some updates to your integration if your integration automatically categorizes applications in the New Applicant stage by doing the following:
- Adds or removes tags to known existing candidates in Lever using the Create a candidate endpoint or the Update candidate tags endpoints
- Changes the stage of candidate profiles using the Update candidate stage endpoint
- Archives candidates using the Update candidate archived state endpoint
Aside from that, there are just a few things to note about how the eventual migration of candidate data to the Opportunities data model may affect your integration temporarily.
Next steps and potential impact of not updating integrations
If your integration adds or removes tags from existing candidate profiles with POST /candidates requests to the Create a candidate endpoint or the Update candidate tags endpoints you'll need to update the integration.To add or remove tags, use the Update opportunity tags endpoints.
Impact: New POST /candidate requests will create a new opportunity with the specified tag. The new opportunity will be linked to the candidate’s contact.
Please Note: The Update candidate tags endpoints are deprecated but maintained for backwards compatibility and will continue to work as expected. However, we recommend updating your integration to use the new Update opportunity tags endpoints. Changes the stage of candidate profiles using the Update candidate stage endpoint
Changes the stage of candidate profiles using the Update candidate stage endpoint
If your integration changes the stage of candidate profiles with the Update candidate stage endpoint you'll need to update the integration. To update an opportunity's stage, use the Update opportunity stage endpoint.
Impact: The Update candidate stage endpoint is deprecated but maintained for backwards compatibility and will continue to work as expected. However, we recommend updating your integration to use the new Update opportunity stage endpoint.
Archives candidates using the Update candidate archived state endpoint
Preparing for the candidate data migration
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.
This means that a candidate may now have multiple active opportunities in the New Applicant stage, and your integration can and should process each individually. If a candidate is split up into multiple opportunities during the migration, the original, pre-migration candidateId will be given to the opportunity for the most recently added application that is still active.
We will give you several warnings about when your candidate data migration to the new Opportunities data model will take place, and we recommend pausing your integration during the migration of your account.