Ashby Assessment API

openapi: 3.1.0
info:
  version: 1.0.0
  title: Ashby API Key Assessment 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: Assessment
paths:
  /assessment.addCompletedToCandidate:
    post:
      summary: assessment.addCompletedToCandidate
      operationId: assessmentAddCompletedToCandidate
      description: 'Add a completed assessment to a candidate


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

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                candidateId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the candidate, to whom to add the completed assessment
                partnerId:
                  allOf:
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                  - description: The id of the partner adding the assessment
                assessment:
                  type: object
                  description: The completed assessment
                  required:
                  - assessmentTypeId
                  - assessmentId
                  - assessmentName
                  - result
                  - metadata
                  properties:
                    assessmentTypeId:
                      allOf:
                      - description: An identifier that uniquely identifies the assessment type
                      - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                    assessmentId:
                      allOf:
                      - description: An identifier that uniquely identifies the completed assessment
                      - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                    assessmentName:
                      type: string
                      example: Node Assessment
                      description: The name of the assessment that was taken that will be displayed in the UI
                    result:
                      allOf:
                      - description: The assessment's result
                      - $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                    metadata:
                      type: array
                      description: An array of metadata associated with this completed assessment
                      items:
                        $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                timestamp:
                  allOf:
                  - description: The timestamp in milliseconds since the unix epoch, when the assessment was completed
                  - type: integer
                    description: The timestamp in milliseconds since the unix epoch, when the update occurred
                    format: int64
                    example: 1665680638489
              required:
              - candidateId
              - partnerId
              - assessment
              - timestamp
      responses:
        '200':
          description: Responses for the assessment.addCompletedToCandidate 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'
                  - properties:
                      results:
                        type: object
                        required:
                        - assessmentTypeId
                        - assessmentId
                        - assessmentName
                        - candidateId
                        - metadata
                        properties:
                          applicationId:
                            allOf:
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          assessmentId:
                            allOf:
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          assessmentName:
                            type: string
                            example: test-assessment-name
                          assessmentTypeId:
                            allOf:
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          candidateId:
                            allOf:
                            - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                          metadata:
                            type: array
                            items:
                              $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                          result:
                            type: object
                            properties:
                              identifier:
                                type: string
                                description: Uniquely identifies this field, for this partner
                                example: result-max
                              label:
                                type: string
                                description: Label for the assessment metadata to be displayed in the UI
                                example: Max Score
                              description:
                                type: string
                                description: Description of the assessment metadata, which may be displayed in the UI
                                example: The maximum possible score for the assessment
                              type:
                                type: string
                                description: The type of the value. Please reach out if you'd like us to support a new type!
                                enum:
                                - numeric_score
                                - numeric_duration_minutes
                                - url
                                - string
                                - boolean_success
                              value:
                                allOf:
                                - oneOf:
                                  - type: string
                                  - type: number
                                  - type: boolean
                                  description: 'The raw value — one of string, number, or boolean

                                    '
                                - example: 10
                            required:
                            - identifier
                            - label
                            - type
                            - value
                  - required:
                    - results
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /assessment.start:
    post:
      summary: assessment.start (Implemented by Partner)
      operationId: assessmentStart
      description: 'The API for starting an assessment. Implemented by the partner, called by Ashby.

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - assessment_type_id
              - candidate
              - application
              - job
              properties:
                assessment_type_id:
                  allOf:
                  - description: The id of the type of assessment to start (retrieved from calling /assessment.list)
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                candidate:
                  allOf:
                  - description: Identifier of the assessment being started
                  - type: object
                    description: A description of the candidate
                    required:
                    - ashby_id
                    - first_name
                    - last_name
                    - email
                    - ashby_profile_url
                    properties:
                      ashby_id:
                        allOf:
                        - type: string
                        - description: The identifier of the candidate in Ashby
                      first_name:
                        allOf:
                        - type: string
                        - description: The first name of the candidate being assessed
                      last_name:
                        allOf:
                        - type: string
                        - description: The last name of the candidate being assessed
                      email:
                        allOf:
                        - type: string
                        - description: The email of the candidate being assessed
                      ashby_profile_url:
                        allOf:
                        - type: string
                        - description: The url back into Ashby of the candidate being assessed
                application:
                  allOf:
                  - description: The application for which the candidate is being assessed
                  - type: object
                    description: The application for which the candidate is being assessed
                    required:
                    - ashby_id
                    - status
                    properties:
                      ashby_id:
                        allOf:
                        - type: string
                        - description: The id of the application in Ashby
                      status:
                        allOf:
                        - $ref: '#/paths/~1application.list/post/requestBody/content/application~1json/schema/allOf/1/properties/status'
                        - description: The status of the application in Ashby
                job:
                  allOf:
                  - description: The job for which the candidate is being assessed
                  - type: object
                    description: The job for which the candidate is being assessed
                    required:
                    - ashby_id
                    - name
                    - ashby_job_url
                    properties:
                      ashby_id:
                        allOf:
                        - type: string
                        - description: The id of the job in Ashby
                      name:
                        allOf:
                        - type: string
                        - description: The name of the job in Ashby
                      req_id:
                        allOf:
                        - type: string
                        - description: The customer-defined requisition id for the job
                      ashby_job_url:
                        allOf:
                        - type: string
                        - description: The url of the job, internal to Ashby
                      hiringTeam:
                        type: array
                        items:
                          $ref: '#/paths/~1hiringTeam.addMember/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results'
      responses:
        '200':
          description: Responses for the assessment.start endpoint
          content:
            application/json:
              schema:
                title: Success Response
                type: object
                required:
                - success
                - results
                properties:
                  success:
                    type: boolean
                  results:
                    required:
                    - assessment_id
                    properties:
                      assessment_id:
                        type: string
                      update_request:
                        $ref: '#/paths/~1assessment.update/post/requestBody/content/application~1json/schema'
        '409':
          description: 'The assessment could not be started because the candidate is already being assessed.

            '
        '422':
          description: 'A custom error message that will be shown to the user in Ashby.

            '
          content:
            application/json:
              schema:
                title: Custom Error Response
                type: object
                required:
                - message
                properties:
                  message:
                    type: string
                    description: The message to be shown to the user in Ashby.
  /assessment.list:
    post:
      summary: assessment.list (Implemented by Partner)
      operationId: assessmentList
      description: 'The API for listing assessments that the partner supports — implemented by the partner, but called by Ashby

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Responses for the assessment.list 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: array
                        items:
                          allOf:
                          - type: object
                            description: List of available assessments
                            properties:
                              assessment_type_id:
                                allOf:
                                - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                              name:
                                type: string
                              description:
                                type: string
                - $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /assessment.update:
    post:
      summary: assessment.update
      operationId: assessmentUpdate
      description: 'Update Ashby about the status of a started assessment.


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


        `assessment_status` is required unless `cancelled_reason` is provided.

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - assessment_id
              - timestamp
              properties:
                assessment_id:
                  allOf:
                  - description: Identifier of the assessment being updated
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
                timestamp:
                  $ref: '#/paths/~1assessment.addCompletedToCandidate/post/requestBody/content/application~1json/schema/properties/timestamp/allOf/1'
                assessment_status:
                  allOf:
                  - description: The current status of the assessment. Setting this with a value of "Started" will signal Ashby to store the timestamp the assessment started. Required when `cancelled_reason` is not set.
                  - $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                assessment_profile_url:
                  allOf:
                  - description: The url back to the assessment/candidate on the partner's website. This value should always be of type url. Required when `assessment_result` is set.
                  - $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                assessment_result:
                  allOf:
                  - description: The result of the assessment. Sending an update with this field will signal to Ashby that the assessment is complete.
                  - $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                cancelled_reason:
                  allOf:
                  - description: The reason the assessment was cancelled. This field will signal to Ashby that the assessment is cancelled.
                  - $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
                metadata:
                  type: array
                  description: Any other metadata about the assessment (e.g. ETA until complete). All assessment data should have unique identifiers.
                  items:
                    $ref: '#/paths/~1assessment.addCompletedToCandidate/post/responses/200/content/application~1json/schema/oneOf/0/allOf/1/properties/results/properties/result'
      responses:
        '200':
          description: Responses for the assessment.start endpoint
  /assessment.cancel:
    post:
      summary: assessment.cancel (Implemented by Partner)
      operationId: assessmentCancel
      description: '(Optional) Cancels an assessment. Implemented by the partner, called by Ashby.

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - assessment_id
              properties:
                assessment_id:
                  allOf:
                  - description: The id of the started assessment to cancel
                  - $ref: '#/paths/~1interviewerPool.addUser/post/requestBody/content/application~1json/schema/properties/userId'
      responses:
        '200':
          description: Responses for the assessment.cancel endpoint
          content:
            application/json:
              schema:
                oneOf:
                - title: Success Response
                  type: object
                  $ref: '#/paths/~1assessment.start/post/responses/200/content/application~1json/schema'
                - title: Error Response
                  type: object
                  $ref: '#/paths/~1report.generate/post/responses/429/content/application~1json/schema'
  /assessment.customField.list:
    post:
      summary: customField.list (Implemented by Partner)
      operationId: assessmentPartnerCustomFieldList
      description: 'The API for listing custom fields that can be synced to Ashby — implemented by the assessment partner, but called by Ashby.


        This endpoint is optional and must be enabled for your integration. Contact Ashby if you wish to use this feature.

        '
      tags:
      - Assessment
      requestBody:
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Responses for the customField.list 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:
                      fields:
                        type: array
                        items:
                          type: object
                          description: A custom field specification provided by an assessment partner
                          properties:
                            id:
                              type: string
                              minLength: 1
                              description: Unique identifier for this custom field. This id will be used as the key in `additional_fields` when calling `/assessment.start`.
                              example: department
                            name:
                              type: string
                              minLength: 1
                              description: Display name of the custom field shown to users in Ashby
                              example: Department
                            type:
                              type: string
                              description: The type of the custom field
                              enum:
                              - String
                              - Date
                              - DateRange
                              - Number
                              - ValueSelect
                              - MultiValueSelect
                              - Boolean
                              - LongText
                              - Email
                              - Phone
                              - Score
                              - SocialLink
                              - Url
                              - Currency
                              - Location
                              example: ValueSelect
                            possible_values:
                              type: array
                              description: Required for `ValueSelect` and `MultiValueSelect` types. An array of possible values the user can choose from.
                              items:
                                type: object
                                properties:
                                  key:
                                    type: string
                                    minLength: 1
                                    description: Internal identifier for this option. This value will be sent in `additional_fields` when the assessment is started.
                                    example: eng
                                  value:
                                    type: string
                                    minLength: 1
                                    description: Display value shown to users in Ashby
                                    example: Engineering
                                required:
                                - key
                                - value
                            isRequired:
                              type: boolean
                              description: Whether this field is required. Defaults to false if not specified.
                              example: false
                          required:
                          - id
                          - name
                          - type
                    required:
                    - fields
                - $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.