Lever Postings API

openapi: 3.1.0
info:
  title: Lever Data Applications Postings 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: Postings
  description: Job postings published to the company careers site.
paths:
  /postings:
    get:
      tags:
      - Postings
      summary: List Postings
      operationId: listPostings
      parameters:
      - $ref: '#/components/parameters/Limit'
      - $ref: '#/components/parameters/Offset'
      responses:
        '200':
          description: A page of postings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostingList'
    post:
      tags:
      - Postings
      summary: Create A Posting
      operationId: createPosting
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostingCreate'
      responses:
        '201':
          description: Posting created.
  /postings/{id}:
    parameters:
    - name: id
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Postings
      summary: Retrieve A Posting
      operationId: getPosting
      responses:
        '200':
          description: The posting.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Posting'
    put:
      tags:
      - Postings
      summary: Update A Posting
      operationId: updatePosting
      responses:
        '200':
          description: Posting updated.
  /{site}:
    parameters:
    - name: site
      in: path
      required: true
      description: Lever company site name (e.g. `acmeco`).
      schema:
        type: string
    get:
      tags:
      - Postings
      summary: List Public Postings
      description: 'Returns a paginated list of published postings for the given Lever site. Supports JSON (default),

        HTML, and iframe response modes via the `mode` query parameter.

        '
      operationId: listPublicPostings
      parameters:
      - name: skip
        in: query
        schema:
          type: integer
      - name: limit
        in: query
        schema:
          type: integer
          maximum: 100
      - name: location
        in: query
        schema:
          type: string
      - name: commitment
        in: query
        schema:
          type: string
      - name: team
        in: query
        schema:
          type: string
      - name: department
        in: query
        schema:
          type: string
      - name: level
        in: query
        schema:
          type: string
      - name: group
        in: query
        description: Group results by `location`, `commitment`, `team`, `department`, or `level`.
        schema:
          type: string
      - name: mode
        in: query
        description: Response format.
        schema:
          type: string
          enum:
          - json
          - html
          - iframe
          - xml
      - name: css
        in: query
        description: Optional URL of a CSS stylesheet to apply when mode is `html` or `iframe`.
        schema:
          type: string
      - name: resize
        in: query
        description: Enable iframe auto-resize.
        schema:
          type: boolean
      responses:
        '200':
          description: A page of postings, or HTML / XML content depending on `mode`.
  /{site}/{postingId}:
    parameters:
    - name: site
      in: path
      required: true
      schema:
        type: string
    - name: postingId
      in: path
      required: true
      schema:
        type: string
    get:
      tags:
      - Postings
      summary: Retrieve A Public Posting
      description: Returns a single published posting as JSON.
      operationId: getPublicPosting
      responses:
        '200':
          description: The posting.
components:
  schemas:
    Posting:
      type: object
      properties:
        id:
          type: string
        text:
          type: string
        state:
          type: string
          enum:
          - draft
          - internal
          - published
          - closed
        categories:
          type: object
          properties:
            commitment:
              type: string
            location:
              type: string
            team:
              type: string
            department:
              type: string
            level:
              type: string
        country:
          type: string
        createdAt:
          type: integer
          format: int64
        updatedAt:
          type: integer
          format: int64
        hostedUrl:
          type: string
          format: uri
        applyUrl:
          type: string
          format: uri
        workplaceType:
          type: string
          enum:
          - on-site
          - hybrid
          - remote
          - unspecified
        salaryRange:
          type: object
          properties:
            min:
              type: number
            max:
              type: number
            currency:
              type: string
            interval:
              type: string
        owner:
          type: string
    PostingCreate:
      type: object
      required:
      - text
      properties:
        text:
          type: string
        state:
          type: string
        categories:
          type: object
        owner:
          type: string
    PostingList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Posting'
        hasNext:
          type: boolean
        next:
          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
    Offset:
      name: offset
      in: query
      description: Opaque cursor returned in the previous response's `next` field.
      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.