openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Interviewer Pool API
  description: Complete public API for accessing resources in your Ashby instance. Includes applications, candidates, jobs, interviews, offers, surveys, custom fields, organization metadata, files, reports, approvals, and webhooks.
  contact:
    name: Ashby Support
    url: https://app.ashbyhq.com/support
    email: support@ashbyhq.com
servers:
- url: https://api.ashbyhq.com
security:
- BasicAuth: []
tags:
- name: Interviewer Pool
paths:
  /interviewerPool.list:
    post:
      summary: interviewerPool.list
      operationId: interviewerPoolList
      description: 'List all interviewer pools.


        See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for detailed usage examples.


        **Requires the [`hiringProcessMetadataRead`](authentication#permissions-interviewerpoollist) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/paths/~1surveyFormDefinition.list/post/requestBody/content/application~1json/schema'
              - type: object
                properties:
                  includeArchivedPools:
                    type: boolean
                    description: When true, includes archived pools
                    default: false
                  includeArchivedTrainingStages:
                    type: boolean
                    description: When true, includes archived training stages
                    default: false
      responses:
        '200':
          description: Responses from the interviewerPool.list endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              allOf:
                              - description: The pool's id
                              - example: 3ae2b801-19f6-41ef-ad28-214bd731948f
                              - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                            title:
                              type: string
                              example: Backend Technical Screeners
                              description: The pool's title
                            isArchived:
                              allOf:
                              - $ref: '#/webhooks/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening/properties/isArchived'
                              - description: Whether or not the pool is archived
                            trainingPath:
                              type: object
                              properties:
                                id:
                                  allOf:
                                  - description: The training path's id
                                  - example: 3ae2b801-19f6-41ef-ad28-214bd731948f
                                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                enabled:
                                  type: boolean
                                  description: Whether or not the training path is enabled
                                  example: true
                                trainingStages:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      id:
                                        allOf:
                                        - description: The training stage's id
                                        - example: 3ae2b801-19f6-41ef-ad28-214bd731948f
                                        - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                      interviewerRole:
                                        type: string
                                        enum:
                                        - Shadow
                                        - ReverseShadow
                                        description: The role of the interviewer for this stage
                                        example: Shadow
                                      interviewsRequired:
                                        type: integer
                                        description: The number of interviews required for this stage
                                        example: 2
                                      isArchived:
                                        type: boolean
                                        description: Whether or not the training stage is archived
                                        example: false
                                      approvalRequired:
                                        type: boolean
                                        description: Whether or not approval is required for this stage
                                        example: true
                                      approvers:
                                        type: array
                                        items:
                                          $ref: '#/paths/~1user.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                                    required:
                                    - id
                                    - interviewerRole
                                    - interviewsRequired
                                    - isArchived
                                    - approvalRequired
                              required:
                              - id
                              - enabled
                              - trainingStages
                          required:
                          - id
                          - title
                          - isArchived
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.info:
    post:
      summary: interviewerPool.info
      operationId: interviewerPoolInfo
      description: 'Get information about an interviewer pool.


        **Requires the [`hiringProcessMetadataRead`](authentication#permissions-interviewerpoolinfo) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
              required:
              - interviewerPoolId
      responses:
        '200':
          description: Responses from the interviewerPool.info endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        allOf:
                        - $ref: '#/paths/~1interviewerPool.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/items'
                        - type: object
                          properties:
                            qualifiedMembers:
                              type: array
                              items:
                                allOf:
                                - $ref: '#/paths/~1user.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                                - type: object
                                  description: A user who is a qualified member of an interviewer pool.
                                  properties:
                                    isPaused:
                                      type: boolean
                                      description: Whether the user is currently paused from interviewing in this pool.
                                      example: false
                                  required:
                                  - isPaused
                            trainees:
                              type: array
                              items:
                                allOf:
                                - $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/allOf/1/properties/qualifiedMembers/items'
                                - properties:
                                    currentProgress:
                                      type: object
                                      properties:
                                        trainingPathId:
                                          $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                          description: The id of the training path the user is currently on
                                        trainingPathStageId:
                                          $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                          description: The id of the training stage the user is currently in
                                        interviewsCompleted:
                                          type: integer
                                          description: The number of interviews the user has completed in the current stage
                                          example: 1
                                      required:
                                      - trainingPathId
                                      - trainingPathStageId
                                      - interviewsCompleted
                                required:
                                - currentProgress
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.create:
    post:
      summary: interviewerPool.create
      operationId: interviewerPoolCreate
      description: 'Create an interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolcreate) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: The title of the interviewer pool
                  example: Engineering
                requiresTraining:
                  type: boolean
                  description: Whether the interviewer pool requires training
                  example: true
              required:
              - title
      responses:
        '200':
          description: Responses from the interviewerPool.create endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.update:
    post:
      summary: interviewerPool.update
      operationId: interviewerPoolUpdate
      description: 'Update an interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolupdate) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                title:
                  type: string
                  description: The title of the interviewer pool
                  example: Engineering
                requiresTraining:
                  type: boolean
                  description: Whether the interviewer pool requires training
                  example: true
              required:
              - interviewerPoolId
      responses:
        '200':
          description: Responses from the interviewerPool.update endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.archive:
    post:
      summary: interviewerPool.archive
      operationId: interviewerPoolArchive
      description: 'Archives an interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolarchive) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
              required:
              - interviewerPoolId
      responses:
        '200':
          description: Responses from the interviewerPool.archive endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.restore:
    post:
      summary: interviewerPool.restore
      operationId: interviewerPool.restore
      description: 'Restores an archived interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolrestore) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
              required:
              - interviewerPoolId
      responses:
        '200':
          description: Responses from the interviewerPool.restore endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.addUser:
    post:
      summary: interviewerPool.addUser
      operationId: interviewerPoolAddUser
      description: 'Add a user to an interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpooladduser) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                userId:
                  type: string
                  format: uuid
                  example: e9ed20fd-d45f-4aad-8a00-a19bfba0083e
                interviewerPoolTrainingPathStageId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  description: The ID of the training path stage to add the user to. If this is not provided, the user will be added as a fully qualified member of the pool.
              required:
              - interviewerPoolId
              - userId
      responses:
        '200':
          description: Responses from the interviewerPool.removeUser endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /interviewerPool.removeUser:
    post:
      summary: interviewerPool.removeUser
      operationId: interviewerPoolRemoveUser
      description: 'Remove a user from an interviewer pool.


        **Requires the [`hiringProcessMetadataWrite`](authentication#permissions-interviewerpoolremoveuser) permission.**

        '
      tags:
      - Interviewer Pool
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                interviewerPoolId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                userId:
                  $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
              required:
              - interviewerPoolId
              - userId
      responses:
        '200':
          description: Responses from the interviewerPool.removeUser endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success response
                  allOf:
                  - $ref: '#/paths/~1job.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - type: object
                    properties:
                      results:
                        $ref: '#/paths/~1interviewerPool.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Auth. Send your Ashby API key as the username and leave the password blank.
    WebhookSignature:
      type: apiKey
      in: header
      name: Ashby-Signature
      description: HMAC-SHA256 signature of the webhook payload, used to verify webhook authenticity.