Updating your assessment integration for the Opportunities data model

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

You might have developed an assessment integration that allows you to initiate assessments 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 assessments 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

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 assessments 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 assessments in an external system

If your integration initiates assessments 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 an assessment. If you would like to avoid sending assessments for each opportunity for a single candidate, you can check if the candidate has other opportunities by completing the following steps:

1. When an opportunity (opportunityId) enters the trigger stage, take the contactId from the webhook payload.
2. 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 assessment.
3. 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 assessments.

Impact: A person may receive the same assessment they have already been sent or completed if they move to the trigger stage for a new opportunity.

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 will 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.

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.

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 assessment integration.

If your integration initiated an assessment 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 assessments during the migration, you should update your integration to follow these steps:

1. 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
2. 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 assessment.
3. Ensure that your integration can handle the possibility of iterating to update multiple matching opportunities
4. 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.