How do I update my tagging integration for Opportunities?

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.

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:

Next steps and potential impact of not updating integrations

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

If your integration adds or removes tags from existing candidate profiles with the Update candidate tags endpoints, you'll 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'll 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. 

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.

 

 

Have more questions? Submit a request
Powered by Zendesk