Lever Candidates API

openapi: 3.2.0
info:
  title: Lever Candidates API
  version: '2026-11-05'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-05: 114 operation(s) read from 3 public documentation page(s) (each operation names its page in x-source). This is not the provider''s published contract; Lever has published no machine-readable contract that the pipeline could find. Engine: anthropic.'
  x-evidence-tiers:
    code-example: 86
    documentation: 102
    pages-with-code: 2
    pages-read: 3
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-05'
  x-generator: generate-contract-from-docs.py
  x-engine: anthropic
  x-sources:
  - https://hire.lever.co/developer/updates
  - https://hire.lever.co/developer/deprecated
  - https://hire.lever.co/developer/documentation
  x-cleaned: '2026-11-05: 112 operations kept of 188 generated; 88 example-instance paths folded onto their documented template, 76 dropped because their METHOD+path is not on the documentation or Deprecated page (receiver examples, /oauth/token on auth.lever.co, /j/{jid}, literal-id instances already covered). Then 2 documented operation(s) recovered from the earlier generated contract: GET /opportunities/deleted, POST /postings/{posting}/apply.'
servers:
- url: https://api.lever.co/v1
  description: Production (the root URL for the Lever API web service is https://api.lever.co/v1)
- url: https://api.sandbox.lever.co/v1
  description: Integrator Sandbox (partner program; https://hire.lever.co/developer/partner)
security:
- basic: []
tags:
- name: Candidates
paths:
  /candidates:
    get:
      operationId: get_candidates
      tags:
      - Candidates
      summary: List all pipeline Opportunities for Contacts in your Lever account
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: include
        in: query
        required: false
        schema:
          type: string
        description: Include Opportunity followers in list results
      - name: expand
        in: query
        required: false
        schema:
          type: string
        description: Expand application, stage, contact, or user IDs into full objects in response
      - name: tag
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by tag (case sensitive)
      - name: email
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by an email address
      - name: origin
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by origin
      - name: source
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by source
      - name: confidentiality
        in: query
        required: false
        schema:
          type: string
        description: Filter opportunities by confidentiality
      - name: stage_id
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by current stage
      - name: posting_id
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by posting
      - name: archived_posting_id
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by postings for which they have been archived
      - name: created_at_start
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were created (start)
      - name: created_at_end
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were created (end)
      - name: updated_at_start
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were last updated (start)
      - name: updated_at_end
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were last updated (end)
      - name: advanced_at_start
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were advanced to their current stage (start)
      - name: advanced_at_end
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were advanced to their current stage (end)
      - name: archived_at_start
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were archived (start)
      - name: archived_at_end
        in: query
        required: false
        schema:
          type: number
        description: Filter Opportunities by the timestamp they were archived (end)
      - name: archived
        in: query
        required: false
        schema:
          type: boolean
        description: Filter Opportunities by archive status
      - name: archive_reason_id
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by archive reason
      - name: snoozed
        in: query
        required: false
        schema:
          type: boolean
        description: Filter Opportunities by snoozed status
      - name: contact_id
        in: query
        required: false
        schema:
          type: string
        description: Filter Opportunities by contact
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCandidatesResponse'
      x-evidence:
        kind: documentation
    post:
      operationId: post_candidates
      tags:
      - Candidates
      summary: Create a candidate in your Lever account
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: true
        schema:
          type: string
        description: Perform this create on behalf of a specified user
      - name: parse
        in: query
        required: false
        schema:
          type: boolean
        description: If set to true and a resume file is provided, the resume will be parsed
      - name: perform_as_posting_owner
        in: query
        required: false
        schema:
          type: boolean
        description: If set to true, the Opportunity owner will be set to that of the posting owner
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCandidatesResponse'
      x-evidence:
        kind: documentation
  /candidates/{candidate}:
    get:
      operationId: get_candidates_candidate
      tags:
      - Candidates
      summary: Retrieve a single candidate (deprecated endpoint)
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCandidatesCandidateResponse'
      x-evidence:
        kind: documentation
  /candidates/{candidate}/addLinks:
    post:
      operationId: post_candidates_candidate_addLinks
      tags:
      - Candidates
      summary: Add links to a Contact
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateAddlinksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/addPostings:
    post:
      operationId: post_candidates_candidate_addPostings
      tags:
      - Candidates
      summary: Add postings to an Opportunity
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: true
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateAddpostingsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/addSources:
    post:
      operationId: post_candidates_candidate_addSources
      tags:
      - Candidates
      summary: Add sources to an Opportunity
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateAddsourcesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/addTags:
    post:
      operationId: post_candidates_candidate_addTags
      tags:
      - Candidates
      summary: Add tags to an Opportunity
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateAddtagsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/archived:
    put:
      operationId: put_candidates_candidate_archived
      tags:
      - Candidates
      summary: Update an Opportunity's archived state
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutCandidatesCandidateArchivedRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/removeLinks:
    post:
      operationId: post_candidates_candidate_removeLinks
      tags:
      - Candidates
      summary: Remove links from a Contact
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateRemovelinksRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/removeSources:
    post:
      operationId: post_candidates_candidate_removeSources
      tags:
      - Candidates
      summary: Remove sources from an Opportunity
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateRemovesourcesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/removeTags:
    post:
      operationId: post_candidates_candidate_removeTags
      tags:
      - Candidates
      summary: Remove tags from an Opportunity
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCandidatesCandidateRemovetagsRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /candidates/{candidate}/stage:
    put:
      operationId: put_candidates_candidate_stage
      tags:
      - Candidates
      summary: Change an Opportunity's current stage
      x-source: https://hire.lever.co/developer/deprecated
      parameters:
      - name: perform_as
        in: query
        required: false
        schema:
          type: string
        description: Perform this update on behalf of a specified user
      - name: candidate
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutCandidatesCandidateStageRequest'
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
components:
  schemas:
    PostCandidatesCandidateAddlinksRequest:
      type: object
      properties:
        links:
          type: array
          description: Array of links to add to the Contact
      required:
      - links
    PostCandidatesCandidateRemovetagsRequest:
      type: object
      properties:
        tags:
          type: array
          description: Array of tags to remove from this Opportunity
      required:
      - tags
    GetCandidatesResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        headline:
          type: string
        contact:
          type: string
        stage:
          type: string
        stageChanges:
          type: array
        confidentiality:
          type: string
        location:
          type: string
        phones:
          type: array
        emails:
          type: array
        links:
          type: array
        archived:
          type: object
        tags:
          type: array
        sources:
          type: array
        sourcedBy:
          type: string
        origin:
          type: string
        owner:
          type: string
        followers:
          type: array
        applications:
          type: array
        createdAt:
          type: number
        updatedAt:
          type: number
        lastInteractionAt:
          type: number
        lastAdvancedAt:
          type: number
        snoozedUntil:
          type: number
        urls:
          type: object
        dataProtection:
          type: object
        isAnonymized:
          type: boolean
    PutCandidatesCandidateStageRequest:
      type: object
      properties:
        stage:
          type: string
          description: The stage ID of this Opportunity's current stage
      required:
      - stage
    PostCandidatesCandidateAddpostingsRequest:
      type: object
      properties:
        postings:
          type: array
          description: Array of Posting UIDs to be applied to this Opportunity
      required:
      - postings
    PostCandidatesCandidateRemovesourcesRequest:
      type: object
      properties:
        sources:
          type: array
          description: Array of sources to remove from this Opportunity
      required:
      - sources
    GetCandidatesCandidateResponse:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        headline:
          type: string
        contact:
          type: string
        stage:
          type: string
        stageChanges:
          type: array
        confidentiality:
          type: string
        location:
          type: string
        phones:
          type: array
        emails:
          type: array
        links:
          type: array
        archived:
          type: object
        tags:
          type: array
        sources:
          type: array
        sourcedBy:
          type: string
        origin:
          type: string
        owner:
          type: string
        followers:
          type: array
        applications:
          type: array
        createdAt:
          type: number
        updatedAt:
          type: number
        lastInteractionAt:
          type: number
        lastAdvancedAt:
          type: number
        snoozedUntil:
          type: number
        urls:
          type: object
        dataProtection:
          type: object
        isAnonymized:
          type: boolean
    PostCandidatesCandidateRemovelinksRequest:
      type: object
      properties:
        links:
          type: array
          description: Array of links to remove from the Contact
      required:
      - links
    PostCandidatesResponse:
      type: object
      properties:
        deduped:
          type: boolean
        data:
          type: object
    PostCandidatesRequest:
      type: object
      properties:
        name:
          type: string
          description: Contact full name
        headline:
          type: string
          description: Contact headline, typically a list of previous companies or schools
        stage:
          type: string
          description: The stage ID of this Opportunity's current stage
        location:
          type: string
          description: Contact current location
        phones:
          type: array
          description: Contact phone number(s)
        emails:
          type: array
          description: Contact emails
        links:
          type: array
          description: List of Contact links (e.g. personal website, LinkedIn profile, etc.)
        tags:
          type: array
          description: An array containing a list of tags to apply to this Opportunity
        sources:
          type: array
          description: An array containing a list of sources to apply to this Opportunity
        origin:
          type: string
          description: The way this Opportunity was added to Lever
        owner:
          type: string
          description: The user ID of the owner of this Opportunity
        followers:
          type: array
          description: An array of user IDs that should be added as followers to this Opportunity
        resumeFile:
          type: string
          description: Resume file for this Opportunity
        files:
          type: array
          description: File(s) relating to this opportunity
        postings:
          type: array
          description: Array of Posting UIDs
        createdAt:
          type: number
          description: To create a historical Opportunity, set the create time in the past
        archived:
          type: object
          description: Opportunity archived status
    PutCandidatesCandidateArchivedRequest:
      type: object
      properties:
        reason:
          type: string
          description: Archive reason UID - Reason why this candidate is archived for this Opportunity
        cleanInterviews:
          type: boolean
          description: Remove pending interviews from Opportunity when it is archived
        requisitionId:
          type: string
          description: Hire a candidate for the Opportunity against the specific requisition
      required:
      - reason
    PostCandidatesCandidateAddtagsRequest:
      type: object
      properties:
        tags:
          type: array
          description: Array of tags to add to this Opportunity
      required:
      - tags
    PostCandidatesCandidateAddsourcesRequest:
      type: object
      properties:
        sources:
          type: array
          description: Array of sources to add to this Opportunity
      required:
      - sources
  securitySchemes:
    basic:
      type: http
      scheme: basic