Updating your tagging integration for the Opportunities data model

This article will guide you through the steps to update your tagging 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 tagging integration

You may have an integration that helps maintain your candidate database by tagging candidates based on certain criteria. You’ll want to make some updates to your integration if your integration automatically tags candidates by doing the following:

• Adds or removes tags to known existing candidates in Lever using the Update candidate tags endpoints

Next steps and potential impact of not updating integrations

Adds or removes tags to known existing candidates in Lever

If your integration adds or removes tags from existing candidate profiles with the Update candidate tags endpoints, you will want to update the integration to begin using the new Update opportunity tags endpoints.

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.

In this new data model, tags will be stored at the opportunity-level. This means that if a tag that your integration is adding is more relevant to the candidate regardless of opportunity, then you will want to update your integration to take a few additional steps:

1. For any opportunity that triggers your integration, take the contact from the response or webhook payload.
2. Use the List all opportunities endpoint, specifying the contact_id as a query parameter.
3. Ensure that your integration can handle the possibility of iterating to update multiple matching opportunities
4. Use the Update opportunity tags endpoint to any matching opportunityId(s)

If a tag that your integration is adding is indeed more relevant to a specific opportunity for a candidate, then the only update we recommend is switching from the now deprecated but temporarily maintained Update candidate tags endpoints to the new Update opportunity tags endpoints.

Impact: Only updating the tags for one opportunity (candidateId) will add the tags on that one opportunity, instead of potentially all of the candidate's opportunities. The potential downside is that the tag is visible on one opportunity, but not others. Even so, Team Members and Admins filtering the candidate database by the tag will be able to find the candidate because the tag has been added to at least one opportunity for the candidate.