How do I update my data warehouse integration for Opportunities?

With this guide, you can: update your data warehouse or reporting 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.

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’ll 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 Opportunities.
However, even after updating your integration to make it ready for Opportunities, you’ll 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.

Have more questions? Submit a request
Powered by Zendesk