|The information in this article is meant for those that have developed a custom integration using Lever's API.
This article will guide you through the steps to update your data warehouse integration to Lever's Opportunities data model. Before proceeding, we recommend reading our help article on the Opportunities data model in order to understand the general nature of this change.
Your data warehouse integration
You might have developed a data warehouse or reporting integration that allows you to query for candidate data via Lever’s API, store the data, connect it to a business intelligence tool, and ultimately report on your candidate database. You will want to make some updates to your integration if it does the following:
- References the number of unique people in your pipeline or database
If your data warehouse integration primarily reports on the number or status of applications, then your integration is largely ready for the Opportunities data model. However, even after updating your integration to make it ready for the Opportunities data model, you will likely want to be ready to take a few steps just prior to the migration and immediately after.
Next steps and potential impact of not updating integrations
References the number of unique people in your pipeline or database
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. 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.
If your integration currently references the number of unique people in your database using unique candidateIds, then you’ll want to start backfilling a new field - contactId - in your data warehouse. Use the new List all opportunities endpoint, where contact is part of the response for every opportunity.
The contact field will stay consistent between now and after the migration to the Opportunities data model, meaning that you can start backfilling your data warehouse today, and then begin to edit any of your visualizations and reports that are calculating “unique people” or “unique candidates” to use distinct contactIds, instead of distinct candidateIds.
Impact: After the migration to Opportunities, any reports or visualizations that are using distinct candidateIds or opportunityIds to count unique people will actually be counting individual job opportunities.
Preparing for the candidate data migration
We will give you several warnings about when your candidate data migration to the new Opportunities data model will take place, and we strongly suggest temporarily pausing your data warehouse and reporting integrations during the slated migration time. During the migration, API requests will return a 503 response code of Service Unavailable, so there’s no reason to poll for newly updated opportunityIds.
When the migration is complete, the candidates that were split from one candidateId to several opportunityIds will all have the updated_at changed. Because this migration will likely result in a larger than normal number of recently updated opportunityIds, we strongly recommend rate limiting your data warehouse integration’s requests on a temporary basis, until it has “caught up” and captured all of the newly migrated and updated opportunities.