openapi: 3.1.0
info:
  title: Lever Data Applications Opportunities API
  description: 'The Lever Data API exposes the full Lever ATS / CRM recruiting workflow over a JSON REST surface at

    `https://api.lever.co/v1`. It is the integration backbone for Opportunities (candidates), Postings,

    Applications, Interviews, Feedback, Notes, Offers, Requisitions, Stages, Sources, Files, Tags, Users,

    EEO Responses, Audit Events, and Webhooks. Authentication is HTTP Basic with a personal API key or

    OAuth 2.0 Authorization Code Grant. Rate-limited via a token-bucket at 10 requests/second steady-state

    per key with a burst of 20 req/s.

    '
  version: 1.0.0
  contact:
    name: Lever
    url: https://hire.lever.co/developer
  license:
    name: Lever Terms of Service
    url: https://www.lever.co/legal/terms-of-service
servers:
- url: https://api.lever.co/v1
  description: Lever Data API production
security:
- BasicAuth: []
- OAuth2: []
tags:
- name: Opportunities
  description: Opportunities are the unified record for a candidate at a posting (replaces legacy Candidates).
paths:
  /opportunities:
    get:
      tags:
      - Opportunities
      summary: List Opportunities
      description: List all opportunities (candidate records) visible to the API key.
      operationId: listOpportunities
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      - $ref: '#/components/parameters/Expand'
      responses:
        '200':
          description: A page of opportunities.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpportunityList'
    post:
      tags:
      - Opportunities
      summary: Create An Opportunity
      description: Create a new opportunity for a candidate, optionally associating it with one or more postings.
      operationId: createOpportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityCreate'
      responses:
        '201':
          description: Opportunity created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
  /opportunities/{id}:
    parameters:
    - $ref: '#/components/parameters/OpportunityId'
    get:
      tags:
      - Opportunities
      summary: Retrieve An Opportunity
      operationId: getOpportunity
      responses:
        '200':
          description: The opportunity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Opportunity'
    put:
      tags:
      - Opportunities
      summary: Update An Opportunity
      operationId: updateOpportunity
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OpportunityUpdate'
      responses:
        '200':
          description: Opportunity updated.
  /contacts/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Opportunities
      summary: Retrieve A Contact
      operationId: getContact
      responses:
        '200':
          description: The contact (the person across all opportunities).
    put:
      tags:
      - Opportunities
      summary: Update A Contact
      operationId: updateContact
      responses:
        '200':
          description: Contact updated.
  /referrals:
    get:
      tags:
      - Opportunities
      summary: List Referrals
      operationId: listReferrals
      responses:
        '200':
          description: Referrals.
components:
  schemas:
    Opportunity:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        contact:
          type: string
        headline:
          type: string
        stage:
          type: string
        location:
          type: string
        emails:
          type: array
          items:
            type: string
        phones:
          type: array
          items:
            type: object
        archived:
          type: object
          properties:
            archivedAt:
              type: integer
              format: int64
            reason:
              type: string
        createdAt:
          type: integer
          format: int64
        updatedAt:
          type: integer
          format: int64
        applications:
          type: array
          items:
            type: string
        sources:
          type: array
          items:
            type: string
        origin:
          type: string
        owner:
          type: string
        followers:
          type: array
          items:
            type: string
        tags:
          type: array
          items:
            type: string
    OpportunityList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Opportunity'
        hasNext:
          type: boolean
        next:
          type: string
    OpportunityCreate:
      type: object
      required:
      - name
      - emails
      properties:
        name:
          type: string
        emails:
          type: array
          items:
            type: string
        headline:
          type: string
        location:
          type: string
        postings:
          type: array
          items:
            type: string
        owner:
          type: string
        sources:
          type: array
          items:
            type: string
    OpportunityUpdate:
      type: object
      properties:
        name:
          type: string
        headline:
          type: string
        location:
          type: string
        owner:
          type: string
        followers:
          type: array
          items:
            type: string
  parameters:
    Limit:
      name: limit
      in: query
      description: Number of records to return (1-100, default 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 100
    OpportunityId:
      name: id
      in: path
      required: true
      schema:
        type: string
    Offset:
      name: offset
      in: query
      description: Opaque cursor returned in the previous response's `next` field.
      schema:
        type: string
    Expand:
      name: expand
      in: query
      description: Comma-separated list of nested fields to expand inline (e.g. `applications,owner,stage`).
      schema:
        type: string
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using a Lever API key as the username and an empty password.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.lever.co/authorize
          tokenUrl: https://auth.lever.co/oauth/token
          scopes:
            offline_access: Issue refresh tokens.
            opportunities:read:admin: Read opportunities.
            opportunities:write:admin: Write opportunities.
            postings:read:admin: Read postings.
            postings:write:admin: Write postings.
            interviews:read:admin: Read interviews.
            interviews:write:admin: Write interviews.
            feedback:read:admin: Read feedback.
            feedback:write:admin: Write feedback.
            users:read:admin: Read users.
            users:write:admin: Write users.
            requisitions:read:admin: Read requisitions.
            requisitions:write:admin: Write requisitions.
            offers:read:admin: Read offers.
            files:read:admin: Read files.
            files:write:admin: Write files.
            webhooks:read:admin: Read webhook subscriptions.
            webhooks:write:admin: Write webhook subscriptions.
            audit_events:read:admin: Read audit log events.
            eeo_responses:read:admin: Read EEO survey responses.
            eeo_responses_pii:read:admin: Read EEO survey responses with PII.
            confidential:access:admin: Access confidential records.