||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 background check 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 background check integration
You might have developed a background check integration that allows you to initiate background checks for candidates who reach a trigger stage, and then appends the results to their Lever profiles by adding a link or a file. You will want to make some updates to your integration if it does any of the following:
- Checks for tags on candidate profiles to initiate background checks in an external system
- Adds or removes tags to known existing candidates in Lever using the Create a candidate endpoint or the Update candidate tags endpoints
- Adds links or files to known existing candidates in Lever using the Create a candidate endpoint or the Update candidate links or Upload a file endpoints
||In April 2019, we announced the deprecation of the use of the Create a candidate endpoint to add or remove tags, links, or files, but that it would be temporarily maintained for backwards compatibility. Upon migration to Opportunities, continued use of that endpoint for those purposes may lead to unintended consequences.|
Even if your integration does not do any of the above, you may want to take an extra step to prepare your integration to better handle background checks for candidates that are outstanding during the migration of your account to Opportunities.
Next steps and potential impact of declining to update
Checks for tags on candidate profiles to initiate background checks in an external system
If your integration initiates background checks based on the existence of a tag on a candidate profile in a trigger stage, you may want to update your integration to recognize if a candidate has already completed or is in the process of completing a background check. If you would like to avoid requesting background checks for each opportunity for a single candidate, you can check if the candidate has other opportunities by completing the following steps:
- When an opportunity (opportunityId) enters the trigger stage, take the contactId from the webhook payload.
- Use the List all opportunities endpoint, specifying the contact_id as a parameter, in addition to a filter for any tags that indicate an in progress or completed background check.
- If any opportunities are returned, use the Update opportunity tags endpoints to remove and add tags from the opportunity that’s new in stage to reflect that the candidate is already in process or has completed certain background checks.
Impact: The same background check may be conducted for a person if they move to the trigger stage for a new opportunity.
||The List all candidates and Update candidate tags endpoints are deprecated but maintained for backwards compatibility and will continue to work as expected. However, we recommend using the List all opportunities and Update opportunity tags endpoints.|
Adds or removes tags to known existing candidates in Lever
If your integration adds or removes tags from existing candidate profiles with POST /candidates requests to the Create a candidate endpoint, 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.
||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.|
Adds links or files to known existing candidates in Lever
If your integration adds links or files with POST /candidate requests to the Create a candidate endpoint, you'll need to update the integration. To add a file to an existing candidate’s opportunity, use the Upload a file endpoint. To add or remove a link to an existing candidate’s opportunity, use the Update opportunity links endpoints.
Impact: New POST /candidate requests will create a new opportunity with the specified link or file. The new opportunity will be linked to the candidate’s contact.
||The Update candidate links and the Upload a candidate file 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 Upload a file and Update opportunity links endpoints.|
Preparing for the candidate data migration
Your candidates will be migrated to a new data model to support opportunities. On Lever's new data model, a candidate's “opportunities” will have independent candidateIds that will be linked together as part of the same "contact". This means that a candidate may now have multiple active opportunities in the trigger stage for your background check integration.
If your integration initiated a background check before the migration, when a candidate had only a single candidateId, your integration should be prepared for the possibility that a candidate now has opportunityIds (previously candidateId) for multiple, separate opportunities. If a candidate is split up into multiple opportunities during the migration, the original, pre-migration candidateId will become the opportunityId of the opportunity for the most recently added application that is still active.
For candidates with outstanding background checks during the migration, you should update your integration to follow these steps:
- Before submitting an update to a candidate profile in Lever, use the Retrieve a single opportunity endpoint for the candidateId on file to retrieve and store the contactId
- Use the List all opportunities endpoint, specifying the contact_id as a query parameter, in addition to any other other possible filters that make sense for your integration (e.g. tags and stage_id) to find the opportunityId(s) that are relevant—the opportunities that are in the trigger stage for a given background check.
- Ensure that your integration can handle the possibility of iterating to update multiple matching opportunities
- Submit the update to any matching opportunityId(s)
Impact: If you have not updated your integration to check whether a candidate has additional opportunities, using the Upload a file or Update opportunity tags endpoints will only update the candidate profile you specify. If the candidate has other active opportunities, these files or tags may not be visible to all users, depending on their candidate access. Links are shared across all of a candidate’s opportunities and will be visible to anyone who has access to at least one of a candidate’s opportunities.