|
|
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 sourcing 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 sourcing integration
You might have developed a sourcing integration that allows you to engage and source candidates externally and import them into Lever. You will want to make some updates to your integration if your integration does any of the following:
- Creates new candidates in Lever
- Creates new candidates in Lever with the possibility of multiple job postings
- Adds a new posting to a known existing candidate in Lever
- Keeps track of the candidates you've imported into Lever in your own or another external system
Next steps and potential impact of not updating integrations
Creates new candidates in Lever
To better enable development with our new data model, we have added new Opportunities endpoints as a replacement to the now deprecated Candidate endpoints. If your integration creates sourced candidates in Lever with POST /candidates requests to the Create a candidate endpoint, you should update your integration to use the new Create an opportunity endpoint.
Impact: Although we recommend updating your integration to create opportunities using the Opportunities endpoints, the deprecated Create a candidate endpoint is maintained for backwards compatibility and will continue to function as expected.
Creates new candidates in Lever with the possibility of multiple job postings
If your integration to create sourced candidates in Lever has the potential to include multiple job postings in POST /candidates requests to the Create a candidate endpoint, you will need to update the integration. To specify multiple postings for a single candidate, send multiple POST requests to the Create an opportunity endpoint — each with one posting UID in the array for the postings field and with the same email address of the desired candidate.
Impact: Any requests to the Create an opportunity endpoint or Create a candidate endpoint that specify multiple posting UIDs will be rejected.
|
|
The Create a candidate endpoint is deprecated but maintained for backwards compatibility. Although we recommend using the Create an opportunity endpoint, sending multiple POST requests to the Create a candidate endpoint, each with one posting UID in the array for the postings field and with the same email address will also work to add multiple postings for a single candidate. |
Adds a new posting to a known existing candidate in Lever
If your integration adds new postings to existing candidates in Lever via the Add candidate postings endpoint, you will need to update the integration. To add a new opportunity for an existing candidate, use the Create an opportunity endpoint, specifying the email address of the desired candidate. Alternatively, to submit an application on behalf of a candidate, use the Apply to a posting endpoint along with the email address of the desired candidate.
Impact: If a candidate’s opportunity (opportunityId) already has a posting, any subsequent requests to the Add candidate postings endpoint will be rejected.
|
|
The Add candidate postings endpoint is deprecated but maintained for backwards compatibility and will work as expected if the specified opportunity does not already have a posting. However, we recommend using the Create an opportunity endpoint to ensure requests will not be rejected. |
Keeps track of the candidates imported into Lever from an external system
If your integration keeps track of imported candidates to report on their progress or for any other reason, you will need to update the integration. To ensure that you are reporting on all of the relevant opportunities for a given candidate, you should keep track of the contactId as the primary identifier for a person in Lever. In addition, a person may have multiple opportunityId(s) which you should store as ID(s) representing the job opportunities for a candidate that will be reported on.
- If you do not have the contactId for a given candidate, use the Retrieve a single opportunity endpoint for the candidateId on file to retrieve and store the contact.
- Use the List all opportunities endpoint, specifying the contactId as a query parameter, in addition to any other possible filters that make sense for your integration (e.g. sources or tags) to find the opportunityId(s) that are relevant—the opportunities that your integration sourced.
- Ensure that your integration can handle the possibility of needing to report on the progress of multiple opportunityIds or opportunities for a single person (contactId).
Impact: If a candidate your integration has created has multiple applications in Lever, when the customer's candidate database is converted to the new Opportunities data model, the one candidateId your integration has on file may only pertain to one of potentially several opportunities (opportunityIds) for a single person (contactId).