---
title: "assessment.start (Implemented by Partner)"
method: POST
path: "/assessment.start"
tags: ["Assessment"]
---

# assessment.start (Implemented by Partner)

`POST /assessment.start`

The API for starting an assessment. Implemented by the partner, called by Ashby.

## Request body

- object
  - `assessment_type_id` string, uuid, required — The id of the type of assessment to start (retrieved from calling /assessment.list)
  - `candidate` object, required — A description of the candidate
    - `ashby_id` string, required — The identifier of the candidate in Ashby
    - `first_name` string, required — The first name of the candidate being assessed
    - `last_name` string, required — The last name of the candidate being assessed
    - `email` string, required — The email of the candidate being assessed
    - `ashby_profile_url` string, required — The url back into Ashby of the candidate being assessed
  - `application` object, required — The application for which the candidate is being assessed
    - `ashby_id` string, required — The id of the application in Ashby
    - `status` 'Hired' | 'Archived' | 'Active' | 'Lead', required — The status of the application in Ashby
  - `job` object, required — The job for which the candidate is being assessed
    - `ashby_id` string, required — The id of the job in Ashby
    - `name` string, required — The name of the job in Ashby
    - `req_id` string — The customer-defined requisition id for the job
    - `ashby_job_url` string, required — The url of the job, internal to Ashby
    - `hiringTeam` OverlayHiringTeamRole[]
      - `email` string, required
      - `firstName` string, required
      - `lastName` string, required
      - `role` string, required
      - `userId` string, uuid, required

## Response `200`

Responses for the assessment.start endpoint

- AssessmentStartResponse
  - `success` boolean, required
  - `results` object, required
    - `assessment_id` string, required
    - `update_request` OverlayAssessmentUpdateRequest
      - `assessment_id` string, uuid, required — Identifier of the assessment being updated
      - `timestamp` integer, required — The timestamp in milliseconds since the unix epoch, when the update occurred
      - `assessment_status` object — 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.
        - `identifier` string, required — Uniquely identifies this field, for this partner
        - `label` string, required — Label for the assessment metadata to be displayed in the UI
        - `description` string — Description of the assessment metadata, which may be displayed in the UI
        - `type` 'numeric_score' | 'numeric_duration_minutes' | 'url' | 'string' | 'boolean_success', required — The type of the value. Please reach out if you'd like us to support a new type!
        - `value` union, required
          - string
          - number
          - boolean
      - `assessment_profile_url` object — 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.
        - `identifier` string, required — Uniquely identifies this field, for this partner
        - `label` string, required — Label for the assessment metadata to be displayed in the UI
        - `description` string — Description of the assessment metadata, which may be displayed in the UI
        - `type` 'numeric_score' | 'numeric_duration_minutes' | 'url' | 'string' | 'boolean_success', required — The type of the value. Please reach out if you'd like us to support a new type!
        - `value` union, required
          - string
          - number
          - boolean
      - `assessment_result` object — The result of the assessment. Sending an update with this field will signal to Ashby that the assessment is complete.
        - `identifier` string, required — Uniquely identifies this field, for this partner
        - `label` string, required — Label for the assessment metadata to be displayed in the UI
        - `description` string — Description of the assessment metadata, which may be displayed in the UI
        - `type` 'numeric_score' | 'numeric_duration_minutes' | 'url' | 'string' | 'boolean_success', required — The type of the value. Please reach out if you'd like us to support a new type!
        - `value` union, required
          - string
          - number
          - boolean
      - `cancelled_reason` object — The reason the assessment was cancelled. This field will signal to Ashby that the assessment is cancelled.
        - `identifier` string, required — Uniquely identifies this field, for this partner
        - `label` string, required — Label for the assessment metadata to be displayed in the UI
        - `description` string — Description of the assessment metadata, which may be displayed in the UI
        - `type` 'numeric_score' | 'numeric_duration_minutes' | 'url' | 'string' | 'boolean_success', required — The type of the value. Please reach out if you'd like us to support a new type!
        - `value` union, required
          - string
          - number
          - boolean
      - `metadata` OverlayAssessmentDataValue[] — Any other metadata about the assessment (e.g. ETA until complete). All assessment data should have unique identifiers.
        - `identifier` string, required — Uniquely identifies this field, for this partner
        - `label` string, required — Label for the assessment metadata to be displayed in the UI
        - `description` string — Description of the assessment metadata, which may be displayed in the UI
        - `type` 'numeric_score' | 'numeric_duration_minutes' | 'url' | 'string' | 'boolean_success', required — The type of the value. Please reach out if you'd like us to support a new type!
        - `value` union, required
          - string
          - number
          - boolean

## Other responses

- `409` — The assessment could not be started because the candidate is already being assessed.
- `422` — A custom error message that will be shown to the user in Ashby.

---

[API](https://skmtc.net/ashbyhq/apis/ashby-api.md) · [All operations](https://skmtc.net/ashbyhq/apis/ashby-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ashbyhq/ashby-api/versions/778b919dc743/schema)