---
title: "Create TestOrder"
method: POST
path: "/api/v3/test-order"
tags: ["Test Order"]
---

# Create TestOrder

`POST /api/v3/test-order`

## Request

- Base URL: `https://{tenant_name}.benchling.com`
- URL: `https://{tenant_name}.benchling.com/api/v3/test-order`
- Auth: HTTP bearer

Create a Test Order for a trial sample using a Test Definition in a published assay procedure. New Test Orders start with the `PENDING` or `BLOCKED` status when a discrepancy is detected on the sample or container.

## Required fields

| Field | Description |
| --- | --- |
| `testDefinitionId` | Test Definition to perform. |
| `sampleId` | Unarchived trial sample entity. |
| `procedureId` | Published assay procedure. |

## Constraints

- The Procedure must be an `ASSAY`, have a published version, and include `testDefinitionId` in its published configuration.
- `testDefinitionId` and `containerId`, when present, must reference unarchived objects.
- If `studyIds` is provided, every Study must already be associated with `sampleId`.
- When the Procedure configures allowed dilution factors for this Test Definition, `dilutionFactor` is required and must be one of them. Otherwise, omit it.

## Optional references

- `containerId` identifies the sample container.
- `studyIds` associates the test order with existing studies.

## Request body

- CreateTestOrderInput
  - `containerId` string, nullable: Optional API ID of the container holding the sample. The container must not be archive and must contain the sample.
  - `dilutionFactor` integer, nullable: Optional positive dilution factor. When the selected procedure includes specifies allowed dilution factors for this Test Definition, this value is required and must be one of its configured allowed factors.
  - `procedureId` string, required: The API ID of the assayprocedure to perform the test.
  - `sampleId` string, required: The API ID of the trial sample entity to test. The sample must not be archived and must use a trial sample schema.
  - `studyIds` string[]: ID of the study to create the test order in, as a single-item list. The sample must be associated with the study, and the study's sample test plan must include the procedure for the sample's sample definition.
  - `testDefinitionId` string, required: The API ID of the test definition to perform.

## Response `201`

Created

- TestOrder: A Test Order represents an individual request to perform a specific test on a sample. Each Test Order references a `TestDefinition` that specifies what type of test to perform, and a `sample` (Entity) that is being tested. Test Orders track their lifecycle through `status` (see `TestStatus`), from PENDING when created, through IN_PROGRESS during execution, to COMPLETED or other terminal states. When executed via an Assay workflow, the `procedure` and `procedureMethodExecutionInstance` fields link to the execution context. Results are captured in the `result` field. Test Orders can be associated with `Study` objects for clinical/preclinical workflows and linked to specific plate wells via `plateWellAssociations` for laboratory execution tracking.
  - `__typename` string
  - `analysisComment` string, nullable: Additional comments provided for a test order with a status of blocked, invalid, or canceled.
  - `container` ContainerRef
    - `__typename` string
    - `id` string, api_id
  - `createdAt` string, datetime: Timestamp of when the test order was created.
  - `dilutionFactor` integer, nullable: The dilution factor of the test order.
  - `id` string: The ID of the test order.
  - `modifiedAt` string, datetime: Timestamp of when the test order was last modified.
  - `name` string: The name of the test order.
  - `plateWellAssociations` TestOrderLinkedPlateWell[]: The plate wells this test order has been linked to.
    - `__typename` string
    - `plate` WellPlateRef
      - `__typename` string
      - `id` string, api_id
    - `wellPosition` string: Alphanumeric position of plate well eg. A1, B19
  - `procedure` ProcedureRef
    - `__typename` string
    - `id` string, api_id
  - `procedureMethodExecutionInstance` ProcedureMethodExecutionInstanceRef
    - `__typename` string
    - `id` string, api_id
  - `result` ResultRef
    - `__typename` string
    - `id` string, api_id
  - `retestSourceProcedureMethodExecutionInstance` ProcedureMethodExecutionInstanceRef
    - `__typename` string
    - `id` string, api_id
  - `sample` EntityRef
    - `__typename` string
    - `id` string, api_id
  - `status` 'PENDING' | 'BLOCKED' | 'IN_PROGRESS' | 'CANCELLED' | 'INVALID' | 'COMPLETED': The status of the test order.
  - `testDefinition` TestDefinitionRef
    - `__typename` string
    - `id` string, api_id

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/c9f087b98b8b?raw)