Updating your HRIS integration for the Opportunities data model

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

You might have developed an HRIS integration that allows you to export candidates from Lever into your HRIS for onboarding, payroll, and/or employee records. You will want to make some updates to your integration if it does any of the following:

• Expects candidateId to be the primary identifier or unique key for an individual person in Lever
• Makes asynchronous and potentially long-running data updates between your external system and Lever
• Checks the List all applications endpoint for a candidateId to export candidate-provided information into your HRIS

You do not need to make any changes to your HRIS integration with regards to syncing requisition information between your HRIS and Lever.

Next steps and potential impact of not updating integrations

Expects candidateId to be the primary identifier or unique key for an individual

If your integration stores candidateId as a unique key for an individual person in Lever mapped against another key for the person in the HRIS, you will need to update your integration. Going forward with Opportunities, the contact field is the consistent unique identifier for an individual person in Lever, while the opportunityId (or candidateId) will indicate a specific candidacy or opportunity moving through the pipeline.

For go-forward exports from Lever to your HRIS, you should start storing and keying off of contact, which you can begin doing today regardless of how you identify candidates to be exported to your HRIS:

• Webhooks: contactId is included as part of the payload for each webhook event
• Polling: contact is included in each opportunity object’s response to requests to the List all opportunities endpoint

You may still want your HRIS integration to be aware of opportunityId(s) in addition to contact, because applications, forms, and other sub-objects are created and stored at the opportunities level. Or you may want your HRIS to display the opportunityId(s) as UIDs that Lever users can use to view the candidate and their hired opportunity in Lever. In either case, you will want to begin supporting opportunityIds as an array because candidates will be able to be hired multiple times for different opportunities.

As a best practice, to ensure consistency retroactively, you will want to update current employee information in your HRIS to backfill each record with the appropriate Lever contactId. Again, you can begin backfilling the contact field for any employees in your HRIS by using either the Retrieve a single opportunity endpoint or the List all opportunities endpoint, both of which now include contact as part of the response for each opportunity object.

Impact: If candidateId is used as the key/primary identifier of a person in Lever in the mapping with your HRIS, you may create duplicate records for the same person in your HRIS if a candidate is hired for a second (or third, etc.) time in a separate opportunity.

Makes asynchronous and long-running data updates between your external system and Lever

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—now better represented as Opportunities and opportunityIds. This is particularly relevant if your HRIS integration kicks off while the Candidate is still in the active pipeline, because it means that a Candidate could be split into multiple Opportunities in the same stage for your HRIS integration upon migration.

If your integration was initiated for a candidate 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 for multiple, separate opportunities. If a candidate is split up into multiple opportunities during the migration, the original pre-migration candidateId will be given to the opportunity for the most recently added application that is still active. If no applications are active, then the original pre-migration candidateId will be given to the opportunity for the most recently hired application. This means that in most cases, the candidateId your integration has on file will map to the opportunity that the candidate was actually hired for.

Even so, if your external system needs to send a data update back to, or retrieve additional data from Lever, you should update your integration to follow these steps in order to make the integration even more resilient against the migration:

1. Before submitting any update into Lever, or fetching additional data from Lever, use the Retrieve a single opportunity endpoint for the candidateId on file to retrieve and store the contact
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. archived, archive_reason_id, archived_at, advanced_at, and/or stage_id) to find the opportunityId(s) that are relevant—the opportunities that should be updated (most likely the one(s) that was recently or is soon to be hired, depending on your integration)
3. If necessary, ensure that your integration can handle the possibility of iterating to update multiple matching opportunities
4. Submit or request the desired data for any matching opportunities

Impact: If you have not updated your integration to find the most relevant opportunity to update, it’s possible albeit unlikely that you may or may not be updating the “right” opportunity. However, because HRIS integrations are typically triggered for hired candidates, the opportunity with the original candidateId on file is likely to be the most recently hired opportunity. Or if your HRIS integration is triggered earlier, the opportunity with the original candidateId on file will be indeed be an opportunity created from one of the active applications.

Checks the List all applications endpoint for a candidateId to export candidate information

You may have built an integration that looks for and exports hired candidate information that was submitted via custom questions on an Unlisted job posting. If your integration uses the List all applications endpoint to poll for a candidate's application to specific Unlisted postings, then exports their custom question answers, you'll need to update your integration. On Lever's new data model, you should do the following to export a candidate's answers to custom application questions:

1. Use the List all opportunities endpoint, with the applications field expanded, specifying the contact_id as a query parameter, in addition to any other other possible filters that make sense for your integration (e.g. posting_id) to find the opportunityId(s) that are relevant—the opportunity for the Unlisted posting used to collect information from the candidate.
2. Export the custom question answers from the expanded applications field to your HRIS.

Impact: Using the List all applications endpoint to search by hired candidateId will only return the application that the candidate was hired for.