How do I update my auto-categorization integration for Opportunities?

Lever

November 12, 2021 15:05

With this guide, you can: update your auto-categorization integration for Opportunities and the candidate data migration. Please review this article before proceeding with this guide.

Note: This article is designed for partners and customers who have built custom solutions and integrations using the Data API.

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

Adds or removes tags to known existing candidates in Lever using the Create a candidate endpoint or the Update candidate tags endpoints

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

If your integration archives candidate profiles with the Update candidate archived state endpoint you'll need to update the integration. To update an opportunity's stage, use the Update opportunity archived state endpoint.

Impact: The Update a candidate archived state 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 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.