Ashby Application API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Application 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: Application
paths:
  /application.addHiringTeamMember:
    post:
      summary: application.addHiringTeamMember
      description: "Adds an Ashby user to the hiring team at the application level. \n\n**Requires the [`candidateWrite`](authentication#permissions-applicationaddhiringteammember) permission.**\n"
      operationId: applicationaddhiringteammember
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              required:
              - applicationId
              - teamMemberId
              - roleId
              properties:
                applicationId:
                  allOf:
                  - description: The application to assign the user a role on.
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                teamMemberId:
                  allOf:
                  - description: The id of the user to assign the role to.
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                roleId:
                  allOf:
                  - description: The id of the hiring team role to assign.
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
      responses:
        '200':
          description: Responses for the application.addHiringTeamMember 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/~1hiringTeam.addMember/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                    required:
                    - results
                - title: Error response
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.changeSource:
    post:
      summary: application.changeSource
      operationId: applicationChangeSource
      description: 'Change the source of an application.


        **Requires the [`candidatesWrite`](authentication#permissions-applicationchangesource) permission.**

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              properties:
                applicationId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the application to update the source of
                sourceId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The source to set on the application. Pass null to unset an application's source.
              required:
              - applicationId
              - sourceId
              example:
                applicationId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                sourceId: 2c6991c5-c9e2-4af8-879e-29c5a9d26509
      responses:
        '200':
          description: Responses from the application.changeSource 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: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.changeStage:
    post:
      summary: application.changeStage
      operationId: applicationChangeStage
      description: 'Change the stage of an application


        **Requires the [`candidatesWrite`](authentication#permissions-applicationchangestage) permission.**

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              properties:
                applicationId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the application to update the stage of
                interviewStageId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The interview stage to move the application to.
                archiveReasonId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: "Archive Reason to set when moving to an Interview Stage with type: `Archived`. \nNote: You must pass this parameter when moving to an Interview Stage with type: `Archived`\n"
                archiveEmail:
                  type: object
                  properties:
                    communicationTemplateId:
                      allOf:
                      - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                      - description: 'The id of the communication template to use for the email.

                          Note: This communication template''s intendedTypes must include: `email`.

                          '
                    sendAt:
                      type: string
                      format: date-time
                      description: 'The date and time to send the email as an ISO 8601 date and time string, e.g. `2025-02-24T08:27:01Z`.

                        If omitted, the email will be scheduled for the following morning at 9:32am in your default timezone.

                        If the time is in the past, the email will be sent immediately.

                        Note: If a timezone is not specified, timestamps will be interpreted in UTC, regardless of your timezone setting.

                        '
                  description: 'Email to send to the candidate when moving to an Interview Stage with type: `Archived`.

                    Note: If application is already archived, the email will not be sent.

                    Note: If email send fails, the application stage will not be updated. If this is the case, you can retry the request without this parameter.

                    Note: You may only pass this parameter if the application is moving to an Interview Stage with type: `Archived`.

                    '
                  required:
                  - communicationTemplateId
              required:
              - applicationId
              - interviewStageId
              example:
                applicationId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                interviewStageId: 2c6991c5-c9e2-4af8-879e-29c5a9d26509
      responses:
        '200':
          description: Responses from the application.changeStage 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: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application'
                    required:
                    - results
                - allOf:
                  - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
                  - type: object
                    properties:
                      errors:
                        type: array
                        items:
                          type: string
                          enum:
                          - invalid_input
                          - application_not_found
                          - interview_plan_not_found
                          - interview_stage_not_found
                          - archive_reason_not_found
                          - communication_template_not_found
                          - communication_template_not_allowed
                        description: '| Error Code | Description |

                          |------------|-------------|

                          | `invalid_input` | A parameter is the wrong type |

                          | `invalid_input` | Archive fields are not allowed for non-archive stages |

                          | `invalid_input` | Archive reason ID is required for archive stages |

                          | `application_not_found` |  |

                          | `interview_plan_not_found` |  |

                          | `interview_stage_not_found` |  |

                          | `archive_reason_not_found` |  |

                          | `communication_template_not_found` |  |

                          | `communication_template_not_allowed` | Template contains unresolvable substitution tokens |

                          | `communication_template_not_allowed` | Template intended types does not include ''email'' |

                          | `communication_template_not_allowed` | [Less common] Template is archived |

                          | `communication_template_not_allowed` | [Less common] Template is a one-off template |

                          '
  /application.create:
    post:
      summary: application.create
      operationId: applicationCreate
      description: 'Consider a candidate for a job (eg when sourcing a candidate for a job posting).


        If you''re submitting an application as a job board, use the [`applicationForm.submit`](https://developers.ashbyhq.com/reference/applicationformsubmit) endpoint instead. See [Creating a custom careers page](https://developers.ashbyhq.com/docs/creating-a-custom-careers-page) for details.


        **Requires the [`candidatesWrite`](authentication#permissions-applicationcreate) permission.**


        To set values for custom fields on Applications, use the [`customFields.setValue`](https://developers.ashbyhq.com/reference/customfieldsetvalue) endpoint.

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the candidate to consider for a job
                jobId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the job to consider the candidate for
                interviewPlanId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: 'The id of the interview plan to place the application in. If none is provided, the default interview plan is used.

                      '
                interviewStageId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: "The interview stage of the interview plan (either default or provided) to place the application in. \nIf none is provided, the application is placed in the first \"Lead\" stage. \nYou can also supply the special string \"FirstPreInterviewScreen\", which will choose the first pre-interview-screen stage on the specified job's interview plan.\n"
                sourceId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The source to set on the application being created.
                creditedToUserId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the user the application will be credited to.
                createdAt:
                  allOf:
                  - description: 'An ISO date string to set the application''s `createdAt` timestamp. When this value isn''t provided, the `createdAt` timestamp defaults to the time the call was made.

                      '
                  - $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                applicationHistory:
                  allOf:
                  - type: array
                    description: An array of objects representing the application history.
                    items:
                      type: object
                      properties:
                        stageId:
                          allOf:
                          - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          - description: The ID of the interview stage for this history event. This stage must belong to the interview plan associated with the application.
                        stageNumber:
                          allOf:
                          - type: integer
                          - description: The sort order of this event. 0 is the first, the highest number will be the current stage.
                        enteredStageAt:
                          allOf:
                          - $ref: '#/paths/~1candidate.addEmailMessage/post/requestBody/content/application~1json/schema/properties/sentAt/allOf/0'
                          - description: An ISO date string representing the time the application entered this stage.
                        archiveReasonId:
                          allOf:
                          - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          - description: The ID of the archive reason. If the interview stage is an `Archived` stage type, this field is required.
                      required:
                      - stageId
                      - stageNumber
                      - enteredStageAt
                  - description: 'An array of objects representing the application history.

                      '
              required:
              - candidateId
              - jobId
              example:
                candidateId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                jobId: 2c6991c5-c9e2-4af8-879e-29c5a9d26509
      responses:
        '200':
          description: Responses from the application.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: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.info:
    post:
      summary: application.info
      operationId: applicationInfo
      description: 'Fetch application details by application id or by submitted form instance id (which is return by the `applicationForm.submit` endpoint). If both applicationId and submittedFormInstanceId are provided, we will lookup by applicationId.


        **Requires the [`candidatesRead`](authentication#permissions-applicationinfo) permission.**

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              oneOf:
              - type: object
                properties:
                  applicationId:
                    allOf:
                    - description: The id of the application to fetch.
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  expand:
                    type: array
                    description: "Choose to expand the result and include additional data for related objects. \n"
                    items:
                      type: string
                      enum:
                      - openings
                      - applicationFormSubmissions
                      - referrals
                required:
                - applicationId
              - type: object
                properties:
                  submittedFormInstanceId:
                    allOf:
                    - description: The id of the application's submitted form instance to fetch.
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  expand:
                    type: array
                    description: "Choose to expand the result and include additional data for related objects. \n"
                    items:
                      type: string
                      enum:
                      - openings
                      - applicationFormSubmissions
                required:
                - submittedFormInstanceId
      responses:
        '200':
          description: Responses from the application.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: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application'
                        - type: object
                          properties:
                            openings:
                              description: The openings array will only be included if the `openings` expand parameter is included when the request is made.
                              type: array
                              items:
                                $ref: '#/webhooks/openingCreate/post/requestBody/content/application~1json/schema/properties/data/properties/opening'
                        - type: object
                          properties:
                            applicationHistory:
                              type: array
                              items:
                                $ref: '#/paths/~1application.listHistory/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/items'
                            applicationFormSubmissions:
                              type: array
                              description: Application form submissions. These match the response from the `applicationForm.submit` endpoint. Use of the expand parameter is required to fetch.
                              items:
                                $ref: '#/paths/~1applicationForm.submit/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/submittedFormInstance'
                            referrals:
                              type: array
                              items:
                                type: object
                                properties:
                                  user:
                                    $ref: '#/paths/~1user.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
                                  referredAt:
                                    $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                            resumeFileHandle:
                              description: The id, name and handle for the application's resume
                              $ref: '#/paths/~1candidate.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/fileHandles/items'
                    required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.list:
    post:
      summary: application.list
      operationId: applicationList
      description: 'Gets all applications in the organization.


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


        **Requires the [`candidatesRead`](authentication#permissions-applicationlist) permission.**

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/paths/~1opening.list/post/requestBody/content/application~1json/schema'
              - properties:
                  status:
                    type: string
                    enum:
                    - Hired
                    - Archived
                    - Active
                    - Lead
                  jobId:
                    $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  expand:
                    type: array
                    description: "Choose to expand the result and include additional data for related objects. \n"
                    items:
                      type: string
                      enum:
                      - openings
      responses:
        '200':
          description: Responses from the application.list endpoint
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/paths/~1job.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - properties:
                      results:
                        type: array
                        items:
                          allOf:
                          - $ref: '#/webhooks/pushToHRIS/post/requestBody/content/application~1json/schema/properties/data/properties/application'
                          - $ref: '#/paths/~1application.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/allOf/1'
                  required:
                  - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.listCriteriaEvaluations:
    post:
      summary: application.listCriteriaEvaluations
      operationId: applicationListCriteriaEvaluations
      description: 'Fetch a paginated list of AI criteria evaluations for an application.


        This endpoint returns the AI-generated criteria evaluations that assess how well a candidate meets specific job requirements. Each evaluation contains the outcome, reasoning, and other assessment details.


        This endpoint supports pagination only (not incremental sync). See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for usage examples.


        **Requires the [`candidatesRead`](authentication#permissions-applicationListCriteriaEvaluations) permission.**


        **Note:** This endpoint requires the AI Application Review feature to be enabled for your organization.

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              allOf:
              - type: object
                properties:
                  applicationId:
                    allOf:
                    - description: The id of the application to fetch criteria evaluations for.
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
              - $ref: '#/paths/~1brand.list/post/requestBody/content/application~1json/schema'
              required:
              - applicationId
      responses:
        '200':
          description: Responses for the application.listCriteriaEvaluations endpoint
          content:
            application/json:
              schema:
                oneOf:
                - allOf:
                  - $ref: '#/paths/~1brand.list/post/responses/200/content/application~1json/schema/oneOf/0/allOf/0'
                  - properties:
                      results:
                        type: array
                        items:
                          type: object
                          title: Criteria Evaluation
                          description: An AI-generated evaluation of how well a candidate meets a specific job criterion.
                          properties:
                            id:
                              allOf:
                              - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                              - description: The id of the criteria evaluation.
                            criterion:
                              allOf:
                              - type: object
                                title: Criterion Version
                                description: The criterion that was evaluated, including its configuration and prompt details.
                                properties:
                                  id:
                                    allOf:
                                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                    - description: The id of the criterion version.
                                  title:
                                    type: string
                                    description: The title of the criterion.
                                    example: Location
                                  type:
                                    type: string
                                    description: The type of criterion evaluation.
                                    enum:
                                    - ResumePrompt
                                    - DidAnswerApplicationFormQuestion
                                    - SimilarityToAiGeneratedAnswer
                                    example: ResumePrompt
                                  prompt:
                                    type: string
                                    description: The prompt text used for AI evaluation.
                                    example: Evaluate if the candidate's location aligns with the job requirements.
                                  applicationFormDefinitionId:
                                    anyOf:
                                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                                    - type: 'null'
                                    description: The id of the application form definition (if applicable).
                                  applicationFormFieldPath:
                                    type:
                                    - string
                                    - 'null'
                                    description: The path to the specific application form field (if applicable).
                                required:
                                - id
                                - title
                                - type
                                - prompt
                              - description: The criterion that was evaluated.
                            status:
                              type: string
                              description: The status of the evaluation.
                              enum:
                              - Pending
                              - Completed
                              - Failed
                              - Skipped
                              example: Completed
                            outcome:
                              type:
                              - string
                              - 'null'
                              description: The evaluation outcome (e.g., "Meets", "Does Not Meet").
                              example: Meets
                            reasoning:
                              type:
                              - string
                              - 'null'
                              description: The AI's reasoning for the evaluation outcome.
                              example: The candidate's location in San Francisco aligns well with the job's requirement for Bay Area presence.
                            skipReason:
                              type:
                              - string
                              - 'null'
                              description: The reason why the evaluation was skipped (if status is "Skipped").
                              example: NoResume
                            outcomeNumber:
                              type:
                              - number
                              - 'null'
                              description: A numerical score representing the evaluation outcome (0.0 to 1.0).
                              minimum: 0
                              maximum: 1
                              example: 0.85
                            evaluatedAt:
                              type:
                              - string
                              - 'null'
                              format: date-time
                              description: The date and time when the evaluation was completed.
                              example: '2024-01-15T10:30:00Z'
                          required:
                          - id
                          - criterion
                          - status
                  required:
                  - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /application.listHistory:
    post:
      summary: application.listHistory
      operationId: applicationListHistory
      description: 'Fetch a paginated list of application history items for an application.


        This endpoint supports pagination only (not incremental sync). See the [Pagination and Incremental Synchronization](/docs/pagination-and-incremental-sync) guide for usage examples.


        **Requires the [`candidatesRead`](authentication#permissions-applicationListHistory) permission.**

        '
      tags:
      - Application
      requestBody:
        content:
          application/json:
            schema:
              al

# --- truncated at 32 KB (49 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ashby-hq/refs/heads/main/openapi/ashby-hq-application-api-openapi.yml