A recruiter asks an AI assistant to prepare an interview brief. The candidate has an archived opportunity for one role and an active opportunity for another. If the integration groups everything by email address, an old rejection can appear as the current hiring decision. A note can also land on the wrong candidacy even though the person's name looks correct.
Start a Lever integration by separating the person from each hiring journey. This guide explains the documented object model and a recommended engineering pattern for using it. The review gates, storage rules and tests below are design recommendations, not built-in guarantees from Lever or an AI model.
What is the difference between a candidate and an opportunity?
Lever defines a candidate profile as information about the person regardless of the jobs they apply for. That includes name, location, email addresses, phone numbers and external profile URLs. An opportunity represents a particular candidacy, with its own stage, origin, source and associated role information.
The same person can therefore appear more than once in a pipeline view. Lever describes that view as a list of opportunities. Repeated names alone do not prove that duplicate candidate profiles exist. Before a cleanup job merges anything, inspect the contact identity and the separate considerations.
| Entity | What it represents | Integration rule |
|---|---|---|
| Candidate profile or contact | The individual across candidacies | Keep a person-level identity record |
| Opportunity | A particular journey through the pipeline | Keep stage and role evidence scoped here |
| Application | An application associated with an opportunity | Preserve its own ID and opportunity link |
| Opportunity resources | Notes, feedback, interviews and other related records | Retain the opportunity association during retrieval |
Keep person IDs and candidacy IDs separate
The Lever API directs integrations to use the contact field as the unique person identifier and opportunityId as the specific candidacy identifier. The Opportunities endpoints replace the deprecated Candidates endpoints. An old variable called candidateId may therefore describe a candidacy rather than the person your application thinks it describes.
Audit that vocabulary before connecting an AI tool. In your own database, use explicit names such as lever_contact_id and lever_opportunity_id. Include an account key in stored identifiers so records from separate customer accounts cannot accidentally join. Do not let a single generic candidate_id column alternate between these meanings.
Email remains useful for finding records, but it should not replace the documented contact identifier after resolution. If identity is uncertain, return an exception for a recruiter rather than quietly choosing the first match.
Retrieve only the context the task needs
Lever's List all opportunities endpoint supports filtering by contact_id. It can expand applications, as well as other documented resources. Use that relationship to enumerate a person's candidacies, then select the one relevant to the request. Do not assume that the first returned opportunity is the current role.
An opportunity has no more than one application according to the API documentation. A person may have multiple applications on different opportunities, and candidates can exist without applying to a specific posting. Handle an absent application as a supported state rather than a parser failure or evidence that the person should be deleted.
Notes and feedback have opportunity-specific retrieval paths. Keep that association when assembling a brief. The candidate history visible in Lever can span opportunities, but a combined history should not erase which role produced a particular interview or note.
Build a role-specific evidence packet
For an interview brief, prepare a packet with the selected opportunity, the role context, the relevant application and the records approved for this task. Each evidence item should carry its source record ID, opportunity ID and retrieval time in your private system. Give the model readable evidence labels rather than a pile of unlabeled text.
Ask it to distinguish current-role evidence from historical context. An earlier interview can provide useful background, but it should remain labeled as earlier evidence for a different consideration. Missing information should remain missing. The model should not fill a gap with an assumption based on a job title.
Keep the brief as a draft until a recruiter checks it. Our AI recruiting agents work focuses on bounded workflows where operators can see the evidence and correct the proposed output before it changes hiring records.
Bind approval to the selected opportunity
A review screen should show the proposed text and the destination together. If a recruiter changes the selected opportunity after reviewing the brief, invalidate the old approval. Re-fetch the intended record before writing and compare the role and status with the reviewed packet. A stale approval should return to review.
Separate preparation from execution in the application backend. The model can propose an action, while trusted code resolves IDs, checks access and enforces the allowed operation. If a write times out, inspect the destination before retrying. Otherwise a successful but unacknowledged action can become a duplicate note.
These are application controls to implement and test. They do not follow automatically from using the Opportunities API. Keep credentials out of prompts and record only the minimum audit details needed to diagnose a wrong-target incident.
Test cases that expose a broken data model
- One contact with an active and an archived opportunity. The brief must use the selected one.
- Two different contacts with the same display name. The system must not join them by name.
- A person with several applications. Each application must retain its opportunity association.
- An opportunity without an application. The workflow must explain the missing context.
- A reviewer switching roles before execution. The earlier approval must no longer authorize the write.
- A delayed response after a write. Recovery must check the intended destination before retrying.
Measure correctness at the record level. A fluent summary attached to the wrong opportunity is a failed test. Include an operator who knows the candidate's history in acceptance review, not just someone checking whether the text reads well.
Common integration mistakes
A frequent design error is counting opportunity rows as unique people. Another is collapsing stage and archive status into a single person-wide value. That loses the distinction between rejection for one role and continued consideration for another. Define which unit each report counts before comparing totals.
The same distinction matters in an ATS migration. Preserve person identity, candidacies and application links separately in the mapping. Resolve how the destination represents them before importing history. Do not flatten the source merely because the target spreadsheet has one row per person.
How Remqa helps with Lever AI workflows
Remqa builds recruiting AI integrations around explicit record mappings, review steps and testable writes. A useful first scope is a draft brief for one selected opportunity, with historical context clearly labeled and no automatic hiring decision. Bring a representative record set and the workflow you want to change. We can discuss the integration boundaries through recruiting hours before deciding what should run automatically.