Ashby Application Form API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Application Form 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 Form
paths:
  /applicationForm.submit:
    post:
      summary: applicationForm.submit
      description: 'Submit an application for a job posting.


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


        The Content-Type of this request must be `multipart/form-data` or `application/json`.


        When using `application/json`, file fields should contain a handle string obtained from [`file.createFileUploadHandle`](https://developers.ashbyhq.com/reference/filecreatefileuploadhandle) with `fileUploadContext` set to `ApplicationForm`. This allows files to be uploaded directly to storage, bypassing the need to send file bytes through the API.


        When using `multipart/form-data`, file fields should reference a file part included in the multipart request body (existing behavior).


        **Important:** Please ensure that you check the response''s `success` field and display any validation errors to candidates if it is `false`. Not doing so will result in applications not being recorded, without any notification to the candidate prompting them to resubmit. For testing purposes, you can simulate a validation failure by submitting the email address `testing-fail-validation@example.com`.


        **Note: The requests generated from this documentation will not work for this endpoint.**


        The values accepted for each field depend on the type of field that''s being filled out:

        - `Boolean` - A boolean value

        - `Date` - A date string in the format YYYY-MM-DD

        - `Email` - A valid email address

        - `Number` - An integer

        - `RichText` - We do not support submitting rich text documents via the API but we do support submitting plain text values for these fields. Plain text values must be submitted in the format `{ type: "PlainText", value: "A plain text string" }`

        - `Score` - An integer between 1 and 4 submitted in the format `{ score: 4 }`

        - `Phone`, `String` A string

        - `ValueSelect` - A string that matches the value of one of the ValueSelect field''s selectable options

        - `MultiValueSelect` - An array of strings that exist in the MultiValueSelect field''s selectable options

        - `Location` - An object with the following properties: `{ country: "USA", city: "San Francisco", region: "California" }`. You may provide any combination of these properties and we will attempt to geocode the location. For best results, provide all three properties.

        - `EducationHistory` - [Early Access] An array of objects with the following properties: `{ schoolName: "University of California, Berkeley", degree: "Bachelor of Science", major: "Computer Science", startDate: "2020-09-01", endDate: "2024-05-15", isCurrent: true }`. Only `schoolName` is required. We will attempt to match the school name to a known school in our database. If `isCurrent` is true, `endDate` must not be provided.

        '
      operationId: applicationformsubmit
      tags:
      - Application Form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - jobPostingId
              - applicationForm
              properties:
                jobPostingId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the job posting to submit an application for
                applicationForm:
                  $ref: '#/paths/~1offer.create/post/requestBody/content/application~1json/schema/properties/offerForm'
                utmData:
                  type: object
                  properties:
                    utm_source:
                      type: string
                    utm_campaign:
                      type: string
                    utm_medium:
                      type: string
                    utm_term:
                      type: string
                    utm_content:
                      type: string
                tagIds:
                  type: array
                  description: The ids of the tags to apply to the candidate
                  items:
                    allOf:
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                allowSubmissionForUnpublishedJobPosting:
                  type: boolean
                  example: true
                  description: Defaults to true. If you are running a custom built careers page that is statically generated, you may want to set this to true to allow applications to be submitted in the time a job is unpublished and your careers page is refreshed. If set to false, applications submitted for unpublished job postings will return a `job_posting_not_published` error.
          multipart/form-data:
            schema:
              type: object
              required:
              - jobPostingId
              - applicationForm
              properties:
                jobPostingId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the job posting to submit an application for
                applicationForm:
                  $ref: '#/paths/~1offer.create/post/requestBody/content/application~1json/schema/properties/offerForm'
                utmData:
                  type: object
                  properties:
                    utm_source:
                      type: string
                    utm_campaign:
                      type: string
                    utm_medium:
                      type: string
                    utm_term:
                      type: string
                    utm_content:
                      type: string
                tagIds:
                  type: array
                  description: The ids of the tags to apply to the candidate
                  items:
                    allOf:
                    - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                allowSubmissionForUnpublishedJobPosting:
                  type: boolean
                  example: true
                  description: Defaults to true. If you are running a custom built careers page that is statically generated, you may want to set this to true to allow applications to be submitted in the time a job is unpublished and your careers page is refreshed. If set to false, applications submitted for unpublished job postings will return a `job_posting_not_published` error.
                <file key>:
                  type: string
                  description: Any file referenced in the `applicationForm`. The name of this field must exactly match the `value` on the `fieldSubmission` that references this file.
                  format: binary
      responses:
        '200':
          description: Responses from the applicationFeedback.submit 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:
                        type: object
                        properties:
                          submittedFormInstance:
                            type: object
                            properties:
                              id:
                                $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                              formDefinition:
                                $ref: '#/paths/~1offer.start/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/formDefinition'
                              submittedValues:
                                type: object
                                example:
                                  _systemfield_name: Gob Bluth
                            required:
                            - id
                            - formDefinition
                            - submittedValues
                          formMessages:
                            allOf:
                            - type: object
                              description: Messages related to the application form submission. Check if the application was blocked before submitting any surveys.
                              properties:
                                blocked:
                                  type: boolean
                                  description: Whether the application was blocked due to configured application limits (eg too many applications submitted for a single candidate). If true, do not attempt to submit any surveys, if any.
                                  example: true
                                blockMessageForCandidateHtml:
                                  type: string
                                  description: A message to display to the candidates regarding the application limits. If there is no message, then the candidate should not be informed that they were blocked.
                                  example: '<div><p>Please Note: we have set up limits for applications for this role. Candidates may not apply more than 2 times in any 60 day span for any job in the Application Limit Group.</p></div>

                                    '
                              required:
                              - blocked
                            - description: "Contains information about the form submission. When `blocked` is true, \nthe application was blocked by organizational rules and no Application \nrecord was created. Do not attempt to call `application.info` with the \n`submittedFormInstanceId` as it will return an `application_blocked` error. \nThe submission is saved as a blocked submission and can be reviewed by \nadministrators.\n"
                        required:
                        - submittedFormInstance
                        - formMessages
                    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.