---
title: "Create PlateRecord"
method: POST
path: "/api/v3/plate-record"
tags: ["Plate Record"]
---

# Create PlateRecord

`POST /api/v3/plate-record`

## Request

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

Create one or more PlateRecords. Three creation modes are supported:

**From scratch**: Provide `name`, `height`, `width`, and any layer fields (`wells`, `concentrationLayers`, `metadataLayers`, etc.).

**From a design template**: Provide `plateDesignTemplateId` to clone a plate design. `height` and `width` default to the design's dimensions. Omitting a layer field preserves the design's layer; supplying an explicit empty list removes it.

## Request body

- CreatePlateRecordInput
  - `barcode` string: Barcode to record as a plate field in the metadata layer.
  - `concentrationLayers` ConcentrationLayerInput[]
    - `concentrationUnitId` string, required
    - `concentrationUnitVersionNumber` integer, required
    - `name` string, required
    - `wells` ConcentrationWellInput[]
      - `concentrationAmount` number, double, nullable, required
      - `wellPosition` string, required
  - `contents` ContentItemInput[]
    - `columnIndex` integer, required
    - `concentrationAmount` number, double
    - `concentrationUnitId` string
    - `concentrationUnitVersionNumber` integer
    - `containerBarcode` string
    - `containerContentsApiIds` string[]
    - `containerId` string
    - `contentLayerName` string
    - `entityId` string
    - `materialInputParameterVersionIdByEntityId` object: The procedure material input each placed entity fulfills, as a map from entity ID to procedure parameter version ID. Only valid when the plate record's auth parent is a procedure step document, and only for the entities this item places (the entity itself, or an entity the container holds); each entity may fulfill at most one material input.
    - `rowIndex` integer, required
    - `testOrderIds` string[]
    - `transferQuantityAmount` number, double
    - `transferQuantityUnitId` string
    - `transferQuantityUnitVersionNumber` integer
    - `wellPosition` string, required
  - `height` integer
  - `measurements` PlateRecordMeasurementInput[]
    - `analyticalMethod` string
    - `columnIndex` integer, required
    - `detectionType` string
    - `measurementConcept` string
    - `measurementIdentifier` string
    - `measurementName` string
    - `measurementUnit` string
    - `measurementValue` number, double
    - `rowIndex` integer, required
  - `metadataLayers` MetadataColumnInput[]
    - `name` string, required
    - `plateValue` union
      - string
      - integer
      - number, double
      - boolean
    - `systemName` string
    - `type` 'text' | 'integer' | 'float' | 'boolean' | 'date' | 'datetime', required
    - `wells` MetadataWellInput[]
      - `value` union, required
        - string
        - integer
        - number, double
        - boolean
      - `wellPosition` string, required
  - `name` string, required
  - `originDesignId` string
  - `parameterLayers` ParameterLayerInput[]
    - `fieldType` 'TEXT' | 'FLOAT' | 'DATETIME', required
    - `name` string, required
    - `parameterVersionId` string, required
    - `wells` ParameterWellInput[]
      - `value` union, required
        - string
        - integer
        - number, double
      - `wellPosition` string, required
  - `plateDesignTemplateId` string
  - `plateReaderAsm` PlateRecordPlateReaderAsmInput
    - `scratchFileId` string, required
  - `plateSchemaId` string
  - `storageId` string: Inventory storage ID to record as a plate field in the metadata layer.
  - `vendorFile` PlateRecordVendorFileInput
    - `scratchFileId` string, required
    - `vendor` string, required
  - `wells` PlateRecordWellInput[]
    - `columnIndex` integer, required
    - `roles` WellRoleInput[]
      - `group` string
      - `role` string, required
      - `subrole` string
    - `rowIndex` integer, required
    - `sampleSchemaId` string
    - `schemaTags` object
    - `wellVolumeAmount` number, double
    - `wellVolumeUnitId` string
    - `wellVolumeUnitVersionNumber` integer
  - `width` integer

## Response `201`

Created

- PlateRecord: A plate design or record used for designing, tracking, and analyzing experimental plates outside of the inventory. Plate records are the working surface for plate-based workflows: you build up a plate's layout (well roles, contents, concentrations, metadata, measurements) through one or more creates and updates, then optionally convert it to a persistent inventory plate via the `bulk-put-in-inventory` endpoint. Each layer of data (label, content, concentration, metadata, measurements, etc.) is accessible via its `dataFrame`. These endpoints are not generally available and may fail depending on your tenant configuration.
  - `__typename` string
  - `barcode` string, nullable: The plate's barcode, when one has been recorded.
  - `createdAt` string, datetime, nullable
  - `height` integer
  - `id` string
  - `isHidden` boolean: Whether the plate record is hidden from the plate's sidebar list.
  - `layers` PlateRecordLayer[]
    - `__typename` string
    - `dataFrame` DataFrameRef
      - `__typename` string
      - `id` string, api_id
    - `name` string
  - `modifiedAt` string, datetime, nullable
  - `name` string
  - `plateSchema` PlateSchemaInterfaceRef
    - `__typename` string
    - `id` string, api_id
  - `storageId` string, nullable: The plate's storage location identifier, when one has been recorded.
  - `width` integer

## 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)