Ashby Application API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Application API
  description: The public API for accessing resources in your Ashby instance.
  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.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`](ref: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`](ref: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.transfer:
    post:
      summary: application.transfer
      operationId: applicationTransfer
      description: 'Transfer an application to a different job.


        **Requires the [`candidatesWrite`](authentication#permissions-applicationtransfer) 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 transfer.
                jobId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the job to transfer the application to.
                interviewPlanId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: "The id of the interview plan to transfer the application to. \n"
                interviewStageId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: "The interview stage of the interview plan to transfer the application to. \n"
                startAutomaticActivities:
                  allOf:
                  - type: boolean
                  - description: "Whether to start any automatic activities set on the target interview stage. \nIf not provided, the default value is `true`.\n"
                  - default: true
              required:
              - applicationId
              - jobId
              - interviewPlanId
              - interviewStageId
              example:
                applicationId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                jobId: 2c6991c5-c9e2-4af8-879e-29c5a9d26509
                interviewPlanId: af94aedd-b743-462c-ab22-9e7e356c11b4
                interviewStageId: 5eb15197-8664-48fd-99cf-fbdc9d25149d
      responses:
        '200':
          description: Responses from the application.transfer 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.update:
    post:
      summary: application.update
      operationId: applicationUpdate
      description: 'Update an application


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


        To set values for custom fields on Applications, use the [`customFields.setValue`](ref:customfieldsetvalue) endpoint.

        '
      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
                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'
                sendNotifications:
                  type: boolean
                  default: true
                  description: Whether or not users who are subscribed to the application should be notified that application was updated. Default is true.
              required:
              - applicationId
              example:
                applicationId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                createdAt: '2021-01-01T00:00:00Z'
                creditedToUserId: 3ae2b801-19f6-41ef-ad28-214bd731948f
                sourceId: 3ae2b801-19f6-41ef-ad28-214bd731948f
      responses:
        '200':
          description: Responses from the application.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: '#/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.updateHistory:
    post:
      summary: application.updateHistory
      operationId: applicationUpdateHistory
      description: 'Update the history of an application. This endpoint is used to update the history of an application, such as setting the entered stage time or deleting a history event.


        **Requires the [`candidatesWrite`](authentication#permissions-applicationupdatehistory) permission and the `Allow updating application history?` setting found in your admin API key permissions configuration.**

        '
      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'
                  applicationHistory:
                    type: array
                    description: The updated array of application history events. This array should contain all history events for the application, not just the events being updated.
                    items:
                      type: object
                      properties:
                        stageId:
                          $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                        stageNumber:
                          type: integer
                          title: Stage Number
                          description: The order of the history event in the application's history. 0 is the first event.
                        enteredStageAt:
                          description: The time the application entered the stage.
                          $ref: '#/paths/~1candidate.createNote/post/requestBody/content/application~1json/schema/properties/createdAt'
                        applicationHistoryId:
                          $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          title: Application History ID
                          description: The id of the application history event to update if you are updating an existing event.
                        archiveReasonId:
                          $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          title: Archive Reason ID
                          description: The id of the archive reason to associate with the history event if the stage type is `archived`.
                      required:
                      - stageId
                      - stageNumber
                      - enteredStageAt
                required:
                - applicationId
                - applicationHistory
      responses:
        '200':
          description: Responses from the application.updateHistory 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'
                        - $ref: '#/paths/~1application.info/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/allOf/1'
                        - 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/p

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