# Add a sample to an order

`POST /v0/labs/order/{order_id}/samples`

> **Authentication:** every request must send `X-ConfidentLims-APIKey`, `X-ConfidentLims-Timestamp` (unix seconds) and `X-ConfidentLims-Signature`, an HMAC-SHA256 signature of the request. The examples below call `sign_request()` from the [Request Signing guide](https://api.confidentcannabis.com/v0/docs/request-signing.md) — read it first. Request bodies are form-encoded (`application/x-www-form-urlencoded`), never JSON.

Add a sample to an existing order and return the updated order.

Send the sample as a single `sample` form field containing the JSON-encoded
object described below. The sample must belong to the same industry as the
rest of the order.

Samples cannot be added to an order that has been canceled or completed;
those requests fail with `invalid_order_status`.

### Sample fields

- `name` (string) — product name for this sample.
- `strain_name` (string) — name of the sample strain. Optional for
  non-cannabis samples.
- `type_id` (int) — ID from the sample type enumeration.
- `production_method_id` (int) — ID from the production method enumeration.
  To submit a blank value, use the category's unnamed production method from
  `GET /sampleproductionmethods` (`99` for cannabis plant samples; other
  categories have their own blank IDs).
- `classification_id` (int) — ID from the sample classification enumeration.
  Use `1` to submit a blank value.
- `test_package_ids` (list of int) — IDs of the test packages ordered for this
  sample.
- `notes` (string, optional) — additional notes about this sample.
- `lims_id` (string, optional) — internal tracking ID for this sample.
- `production_date` (date, optional) — date the sample or product was
  harvested or created.
- `date_samples_collected` (date, optional) — date the sample was collected.
- `batch_id` (string, optional) — batch identifier.
- `batch_size` (float, optional) — batch size.
- `batch_size_unit` (string, optional) — `g` for grams, `units` for units, or
  `lb` for pounds. Defaults to `g`.
- `lot_id` (string, optional) — lot identifier.
- `lot_size` (float, optional) — lot size.
- `lot_size_unit` (string, optional) — `g` for grams, `units` for units, or
  `lb` for pounds. Defaults to `g`.
- `production_run_id` (string, optional) — production run identifier.
- `production_run_size` (float, optional) — production run size.
- `production_run_size_unit` (string, optional) — `g` for grams, `units` for
  units, or `lb` for pounds. Defaults to `g`.
- `manifest_id` (string, optional) — manifest identifier, often for
  seed-to-sale systems.
- `harvest_id` (string, optional) — harvest identifier, often for seed-to-sale
  systems.
- `regulator_sample_id` (string, optional) — seed-to-sale tracking ID for this
  sample.
- `regulator_batch_id` (string, optional) — seed-to-sale batch ID for this
  sample.
- `regulator_lot_id` (string, optional) — seed-to-sale lot ID for this sample.

The following fields are required to calculate mg/container values for
edibles:

- `unit_description` (string, optional) — describes the serving unit of the
  sample.
- `unit_weight` (float, optional) — weight of an individual unit.
- `units_per_serving` (float, optional) — how many units make up one serving.
- `servings_per_container` (float, optional) — how many servings are in a
  container.

The sample object also accepts:

- `send_client_email` (boolean, optional) — if `true` the client receives email
  notifications for the order being edited. Defaults to `true`.

## Path parameters

- `order_id` (string, required)

## Body parameters (application/x-www-form-urlencoded)

- `sample` (string, required) — JSON-encoded sample object — see the field reference below.
  Example:

  ```json
  {
    "name": "Blue Dream - Cured Flower",
    "strain_name": "Blue Dream",
    "type_id": 1,
    "production_method_id": 1,
    "classification_id": 4,
    "test_package_ids": [
      4
    ],
    "notes": "Collected from the north drying room.",
    "lims_id": "LIMS-8841-1",
    "production_date": "2025-02-18",
    "date_samples_collected": "2025-03-13",
    "batch_id": "BD-2503-01",
    "batch_size": 4500.0,
    "batch_size_unit": "g",
    "harvest_id": "HARVEST-2503-BD",
    "regulator_sample_id": "1A4060300003B01000001234",
    "regulator_batch_id": "1A4060300003B01000000987",
    "send_client_email": true
  }
  ```

## Responses

### 200 Success

Fields (alongside the `success: true` envelope flag):

- `order` (object)
  - `id` (string) — Order ID
  - `industry_id` (integer) — Industry ID
  - `industry_name` (string) — Industry Name
  - `lims_id` (string) — Order lims ID
  - `client_id` (integer) — Client ID
  - `status_id` (integer) — Status ID
  - `status_name` (string) — Status Name
  - `lab_license_number` (string) — Lab license number under which order was tested
  - `client_license_number` (string) — Client license number under which order was placed
  - `ordered_date` (timestamp) — Order Date [when order was placed]
  - `verified_date` (timestamp) — Verified Date [when order was verified]
  - `completed_date` (timestamp) — Completed Date [when order was completed]
  - `last_modified` (timestamp) — Time this order was last modified
  - `address` (object)
    - `id` (integer) — Address ID
    - `address_line_1` (string) — Street address line 1
    - `address_line_2` (string) — Street address line 2
    - `city` (string) — City
    - `state_abbreviation` (string) — Two letter state abbreviation
    - `zipcode` (string) — Zipcode
  - `client` (object)
    - `id` (integer) — Client ID
    - `name` (string) — Organization Name
    - `training` (boolean) — Whether this is a training client
    - `last_modified` (timestamp) — Time this client was last modified
    - `email` (string) — Organization Email
    - `phone` (string) — Organization Phone
    - `url` (string) — Organization Website
    - `primary_address` (object)
      - `id` (integer) — Address ID
      - `address_line_1` (string) — Street address line 1
      - `address_line_2` (string) — Street address line 2
      - `city` (string) — City
      - `state_abbreviation` (string) — Two letter state abbreviation
      - `zipcode` (string) — Zipcode
    - `licenses` (array of objects)
      - `id` (integer) — License ID
      - `license_number` (string) — License Number
      - `license_code` (string) — License Code (some states only)
      - `nickname` (string) — Human entered name for license
      - `license_designation_name` (string) — License Designation Name [changes by state]
      - `license_type_name` (string) — License Type Name [changes by state]
  - `samples` (array of objects)
    - `id` (string) — Sample ID
    - `order_id` (string) — Orders ID
    - `client_id` (integer) — Client ID
    - `lab` (object) — Lab
      - `id` (integer) — Lab ID
      - `name` (string) — Lab Name
    - `order_status_id` (integer) — Order Status ID
    - `order_status_name` (string) — Order Status Name
    - `sample_name` (string) — Name of Sample
    - `strain_name` (string) — Name of Sample Strain
    - `sample_industry_id` (integer) — Sample Industry ID
    - `sample_industry_name` (string) — Sample Industry Name
    - `sample_category_id` (integer) — Sample Category ID
    - `sample_category_name` (string) — Sample Category Name
    - `sample_type_id` (integer) — Sample Type ID
    - `sample_type_name` (string) — Sample Type Name
    - `sample_classification_id` (integer) — Sample Classification ID
    - `sample_classification_name` (string) — Sample Classification Name
    - `production_method_name` (string) — Production Method name
    - `production_method_id` (integer) — Production Method ID
    - `regulator_sample_id` (string) — Unique ID from the state's seed-to-sale tracking system of the sample tested by the lab
    - `regulator_batch_id` (string) — Unique ID from the state's seed-to-sale tracking system of the client's batch from which the sample tested by the lab came
    - `batch_id` (string) — Unique ID from the client's inventory management system of the client's batch from which the sample tested by the lab came
    - `harvest_id` (string) — Unique ID from the state's seed-to-sale tracking system of the client's harvest lot from which the sample tested by the lab came
    - `test_packages` (array of objects)
      - `id` (integer) — Unique ID for Test Package
      - `name` (string) — Test Package Name
      - `price` (number) — Package Price - if 0, call for price
      - `minimum_quantity` (number) — Minimum sample quantity required for testing
    - `last_modified` (timestamp) — Time this sample was last modified
    - `date_published` (timestamp) — Published Date [when sample was published]
    - `initial_weight` (number) — Sample weight at order verification
    - `initial_weight_unit` (number) — Unit type for Initial Weight
    - `test_types` (array of objects)
      - `id` (integer) — Unique ID for Test Type
      - `name` (string) — Test Type Name
      - `abbreviation` (string) — Test Type Abbreviation
    - `cover_image` (object)
      - `filename` (string)
      - `public_key` (string (uuid)) — Unique public key for file
      - `url` (string) — Public URL to access file
    - `images` (array of objects) — Will also contain cover image
      - `filename` (string)
      - `public_key` (string (uuid)) — Unique public key for file
      - `url` (string) — Public URL to access file
    - `notes` (string) — Notes about the sample
    - `batch_size` (number) — Size of the client's batch from which the sample tested by the lab came
    - `batch_size_unit` (string) — Unit type for batch size (units, lb, or g)
    - `lot_id` (string) — Unique ID from the client's inventory management system of the client's lot from which the sample tested by the lab came
    - `lot_size` (number) — Size of the client's lot from which the sample tested by the lab came
    - `lot_size_unit` (string) — Unit type for lot size (units, lb, or g)
    - `production_run_id` (string) — Unique ID from the client's inventory management system of the client's production run from which the sample tested by the lab came
    - `production_run_size` (number) — Size of the client's production run from which the sample tested by the lab came
    - `production_run_size_unit` (string) — Unit type for production run size (units, lb, or g)
    - `manifest_id` (string) — Unique ID from the state's seed-to-sale tracking system of the sample manifest from which the sample tested by the lab came
    - `regulator_lot_id` (string) — Unique ID from the state's seed-to-sale tracking system of the client's lot from which the sample tested by the lab came
    - `regulator_sample_id2` (string) — (for Leaf) Pre-Transfer Batch ID
    - `regulator_batch_id2` (string) — (for Leaf) Pre-Transfer Inventory/Lot ID
    - `production_date` (timestamp) — Harvest/Production Date [when sample was produced]
    - `date_samples_collected` (timestamp) — Collection Date [when sample was collected]
    - `public_url` (string) — Unique URL for viewing this sample or CoA without requiring a login. Should be added to CoAs and used for QR codes or other barcode images so end consumers can verify the integrity of the data
    - `units_per_serving` (number) — Serving Size
    - `servings_per_container` (number) — Number of Servings in one Container
    - `unit_description` (string) — Information describing what a "unit" means for this sample (i.e 1 Bottle)
    - `container_description` (string) — Information describing what a "unit" means for this sample (i.e 1 Gummy)
    - `regulatory_category_id` (integer) — Unique ID for sample's regulatory category
    - `solvents_used` (string) — Information about the solvents used in testing
    - `has_coa` (boolean) — True if sample has a Certificate of Analysis
    - `coa` (object) — URL expires after one hour
      - `filename` (string)
      - `public_key` (string (uuid)) — Unique public key for file
      - `url` (string) — Public URL to access file
    - `coa_additions` (array of objects) — URLs expire after one hour
      - `filename` (string)
      - `public_key` (string (uuid)) — Unique public key for file
      - `url` (string) — Public URL to access file
    - `order_lims_id` (string) — Orders lims ID
    - `lims_id` (string) — Sample lims ID
    - `weight_on_hand` (number) — Current weight on hand
    - `weight_on_hand_unit` (string) — Unit type for weight measurements (units, g, or ml)
    - `has_lab_data` (boolean) — True if sample has test results
    - `has_lab_data_draft` (boolean) — True if sample has draft test results
    - `has_coa_draft` (boolean) — True if sample has a draft Certificate of Analysis
    - `coa_draft` (object) — URL expires after one hour
      - `filename` (string)
      - `public_key` (string (uuid)) — Unique public key for file
      - `url` (string) — Public URL to access file
    - `logs` (array of objects)
      - `user_name` (string) — Name of user who added log
      - `user_id` (integer) — Unique ID for user who added log
      - `log_time` (timestamp) — Timestamp of log creation time
      - `message` (string) — Log Content
    - `custom_field` (string) — Custom Field
    - `external_data` (any) — Custom External Json Data
    - `extra_field_1` (string) — Custom data field
    - `extra_field_2` (string) — Custom data field
    - `extra_field_3` (string) — Custom data field
    - `extra_field_4` (string) — Custom data field
    - `extra_field_5` (string) — Custom data field
    - `extra_field_6` (string) — Custom data field
    - `extra_field_7` (string) — Custom data field
    - `extra_field_8` (string) — Custom data field
    - `extra_field_9` (string) — Custom data field
    - `extra_field_10` (string) — Custom data field
    - `extra_date_field_1` (timestamp) — Custom data field for dates
    - `extra_date_field_2` (timestamp) — Custom data field for dates
    - `extra_date_field_3` (timestamp) — Custom data field for dates
    - `extra_date_field_4` (timestamp) — Custom data field for dates
    - `extra_date_field_5` (timestamp) — Custom data field for dates
    - `extra_bool_field_1` (boolean) — Custom data field for yes/no fields
    - `extra_bool_field_2` (boolean) — Custom data field for yes/no fields
    - `extra_bool_field_3` (boolean) — Custom data field for yes/no fields
    - `extra_bool_field_4` (boolean) — Custom data field for yes/no fields
    - `extra_bool_field_5` (boolean) — Custom data field for yes/no fields
    - `test_package_total_price` (number) — Total price of test packages with custom client pricing and discounts included
    - `due_date` (timestamp) — Due date
    - `has_rushed_test_types` (boolean) — True if sample has rushed test types
    - `rushed_test_types` (array of strings) — List of rushed test type abbreviations
  - `logs` (array of objects)
    - `user_name` (string) — Name of user who added log
    - `user_id` (integer) — Unique ID for user who added log
    - `log_time` (timestamp) — Timestamp of log creation time
    - `message` (string) — Log Content
  - `files` (array of objects) — URLs expire after one hour
    - `filename` (string)
    - `public_key` (string (uuid)) — Unique public key for file
    - `url` (string) — Public URL to access file
  - `comments` (string) — Comments entered when placing the order
  - `rejected_message` (string) — Message saved when rejecting the order
  - `verified_message` (string) — Message saved when verifying the order
  - `completed_message` (string) — Message saved when completing the order
  - `discount` (number) — Percent discount applied to order
  - `lab_adjustment` (number) — Flat discount applied to end of order (pre-tax)
  - `sales_tax_rate` (number) — Sales tax rate applied to order
  - `sales_tax_cents` (integer) — Sales tax applied to order (in cents)
  - `subtotal_cents` (integer) — Pre-tax cost for order (in cents)
  - `total_price_cents` (integer) — Final invoice cost for order (in cents)
  - `pickup` (boolean) — Whether this is a pickup or dropoff
  - `secondary_client_type` (integer) — Secondary client type ID
  - `secondary_client_name` (string) — Secondary client name
  - `secondary_client_address` (string) — Secondary client address
  - `secondary_client_license` (string) — Secondary client license

Example:

```json
{
  "success": true,
  "order": {
    "id": "2503GLL0042",
    "industry_id": 1,
    "industry_name": "Cannabis",
    "lims_id": "PO-8841",
    "client_id": 318,
    "status_id": 2,
    "status_name": "Placed",
    "lab_license_number": "C8-0000123-LIC",
    "client_license_number": "CDPH-10003456",
    "ordered_date": "2025-03-14T09:12:44",
    "verified_date": null,
    "completed_date": null,
    "last_modified": "2025-03-14T09:12:44",
    "address": {
      "id": 771,
      "address_line_1": "1400 Industrial Way",
      "address_line_2": "Suite 4",
      "city": "Sacramento",
      "state_abbreviation": "CA",
      "zipcode": "95811"
    },
    "client": {
      "id": 318,
      "name": "Sunrise Cultivation",
      "training": false,
      "last_modified": "2025-02-27T18:04:03",
      "email": "orders@sunrisecultivation.com",
      "phone": "9165550142",
      "url": "https://sunrisecultivation.com",
      "primary_address": {
        "id": 902,
        "address_line_1": "55 Orchard Road",
        "address_line_2": null,
        "city": "Woodland",
        "state_abbreviation": "CA",
        "zipcode": "95695"
      },
      "licenses": [
        {
          "id": 4410,
          "license_number": "CDPH-10003456",
          "license_code": null,
          "nickname": "Woodland cultivation",
          "license_designation_name": "Adult Use",
          "license_type_name": "Cultivation - Small Indoor"
        }
      ]
    },
    "samples": [
      {
        "id": "2503GLL0042.0001",
        "order_id": "2503GLL0042",
        "client_id": 318,
        "lab": {
          "id": 12,
          "name": "Green Leaf Labs"
        },
        "order_status_id": 2,
        "order_status_name": "Placed",
        "sample_name": "Blue Dream - Cured Flower",
        "strain_name": "Blue Dream",
        "sample_industry_id": 1,
        "sample_industry_name": "Cannabis",
        "sample_category_id": 1,
        "sample_category_name": "Plant",
        "sample_type_id": 1,
        "sample_type_name": "Flower, Cured",
        "sample_classification_id": 4,
        "sample_classification_name": "Hybrid",
        "production_method_id": 1,
        "production_method_name": "Indoor",
        "regulator_sample_id": "1A4060300003B01000001234",
        "regulator_batch_id": "1A4060300003B01000000987",
        "batch_id": "BD-2503-01",
        "harvest_id": "HARVEST-2503-BD",
        "test_packages": [
          {
            "id": 4,
            "name": "California Compliance - Flower",
            "price": 275.0,
            "minimum_quantity": 5.0
          }
        ],
        "last_modified": "2025-03-14T09:12:44",
        "date_published": null,
        "order_lims_id": "PO-8841",
        "lims_id": "LIMS-8841-1",
        "notes": "Collected from the north drying room.",
        "batch_size": 4500.0,
        "batch_size_unit": "g",
        "production_date": "2025-02-18",
        "date_samples_collected": "2025-03-13",
        "public_url": "https://confidentcannabis.com/s/2503GLL0042.0001",
        "weight_on_hand": 12.5,
        "weight_on_hand_unit": "g",
        "has_lab_data": false,
        "has_coa": false,
        "coa": null,
        "coa_additions": []
      }
    ],
    "logs": [
      {
        "user_name": "Dana Reyes",
        "user_id": 5501,
        "log_time": "2025-03-14T09:12:44",
        "message": "Order placed"
      }
    ],
    "files": [],
    "comments": "Please prioritise potency.",
    "rejected_message": null,
    "verified_message": null,
    "completed_message": null,
    "discount": 0.0,
    "lab_adjustment": -25.0,
    "sales_tax_rate": 0.0,
    "sales_tax_cents": 0,
    "subtotal_cents": 27500,
    "total_price_cents": 25000,
    "pickup": false,
    "secondary_client_type": 1,
    "secondary_client_name": "Valley Distribution",
    "secondary_client_address": "2100 Harbor Blvd, Oakland, CA 94607",
    "secondary_client_license": "C11-0000456-LIC"
  }
}
```

### 400 Bad request

The request was malformed or failed validation. Validation failures include per-field messages in `error_details`. Possible `error_code` values: `invalid_request`, `request_too_old`.

### 401 Unauthorized

Authentication failed. Possible `error_code` values: `missing_api_key`, `invalid_api_key`, `invalid_credentials_type`, `api_access_restricted`, `api_access_denied`, `missing_signature`, `missing_timestamp`, `invalid_timestamp`, `invalid_signature`.

### 403 Permission denied

The API key is valid but does not have permission for this endpoint (for example, a client key calling a labs endpoint). Possible `error_code` values: `permission_denied`.

### 404 Not found

The requested record does not exist or is not visible to this organization. Possible `error_code` values: `not_found`.

## Examples

### cURL

```bash
# X-ConfidentLims-Signature: see the Request Signing guide - https://api.confidentcannabis.com/v0/docs/request-signing.md
curl -X POST 'https://api.confidentcannabis.com/v0/labs/order/{order_id}/samples' \
  -H 'X-ConfidentLims-APIKey: YOUR_API_KEY' \
  -H 'X-ConfidentLims-Timestamp: UNIX_TIMESTAMP' \
  -H 'X-ConfidentLims-Signature: REQUEST_SIGNATURE' \
  --data-urlencode 'sample={
  "name": "Blue Dream - Cured Flower",
  "strain_name": "Blue Dream",
  "type_id": 1,
  "production_method_id": 1,
  "classification_id": 4,
  "test_package_ids": [
    4
  ],
  "notes": "Collected from the north drying room.",
  "lims_id": "LIMS-8841-1",
  "production_date": "2025-02-18",
  "date_samples_collected": "2025-03-13",
  "batch_id": "BD-2503-01",
  "batch_size": 4500.0,
  "batch_size_unit": "g",
  "harvest_id": "HARVEST-2503-BD",
  "regulator_sample_id": "1A4060300003B01000001234",
  "regulator_batch_id": "1A4060300003B01000000987",
  "send_client_email": true
}'
```

### Python

```python
import time
import requests

# sign_request() is defined in the Request Signing guide:
# https://api.confidentcannabis.com/v0/docs/request-signing.md
from sign_request import sign_request

API_KEY = 'YOUR_API_KEY'
API_SECRET = 'YOUR_API_SECRET'
path = '/v0/labs/order/{order_id}/samples'

data = {
    "sample": "{\n  \"name\": \"Blue Dream - Cured Flower\",\n  \"strain_name\": \"Blue Dream\",\n  \"type_id\": 1,\n  \"production_method_id\": 1,\n  \"classification_id\": 4,\n  \"test_package_ids\": [\n    4\n  ],\n  \"notes\": \"Collected from the north drying room.\",\n  \"lims_id\": \"LIMS-8841-1\",\n  \"production_date\": \"2025-02-18\",\n  \"date_samples_collected\": \"2025-03-13\",\n  \"batch_id\": \"BD-2503-01\",\n  \"batch_size\": 4500.0,\n  \"batch_size_unit\": \"g\",\n  \"harvest_id\": \"HARVEST-2503-BD\",\n  \"regulator_sample_id\": \"1A4060300003B01000001234\",\n  \"regulator_batch_id\": \"1A4060300003B01000000987\",\n  \"send_client_email\": true\n}",
}

headers = {'X-ConfidentLims-Timestamp': str(int(time.time()))}
headers['X-ConfidentLims-Signature'] = sign_request(
    'POST', path, headers, data, API_KEY, API_SECRET)
headers['X-ConfidentLims-APIKey'] = API_KEY

response = requests.post(
    'https://api.confidentcannabis.com' + path,
    headers=headers,
    data=data,
)
print(response.json())
```

### JavaScript

```javascript
// signRequest() is defined in the Request Signing guide:
// https://api.confidentcannabis.com/v0/docs/request-signing.md
import { signRequest } from './sign_request.js';

const API_KEY = 'YOUR_API_KEY';
const API_SECRET = 'YOUR_API_SECRET';
const path = "/v0/labs/order/{order_id}/samples";

const data = {
  "sample": "{\n  \"name\": \"Blue Dream - Cured Flower\",\n  \"strain_name\": \"Blue Dream\",\n  \"type_id\": 1,\n  \"production_method_id\": 1,\n  \"classification_id\": 4,\n  \"test_package_ids\": [\n    4\n  ],\n  \"notes\": \"Collected from the north drying room.\",\n  \"lims_id\": \"LIMS-8841-1\",\n  \"production_date\": \"2025-02-18\",\n  \"date_samples_collected\": \"2025-03-13\",\n  \"batch_id\": \"BD-2503-01\",\n  \"batch_size\": 4500.0,\n  \"batch_size_unit\": \"g\",\n  \"harvest_id\": \"HARVEST-2503-BD\",\n  \"regulator_sample_id\": \"1A4060300003B01000001234\",\n  \"regulator_batch_id\": \"1A4060300003B01000000987\",\n  \"send_client_email\": true\n}",
};

const headers = { 'X-ConfidentLims-Timestamp': String(Math.floor(Date.now() / 1000)) };
headers['X-ConfidentLims-Signature'] = signRequest(
  "POST", path, headers, data, API_KEY, API_SECRET);
headers['X-ConfidentLims-APIKey'] = API_KEY;

const response = await fetch("https://api.confidentcannabis.com" + path, {
  method: "POST",
  headers,
  body: new URLSearchParams(data),
});
console.log(await response.json());
```

---

HTML version: https://api.confidentcannabis.com/v0/docs/labs/add-sample-to-order  
OpenAPI spec for this section: https://api.confidentcannabis.com/v0/docs/labs/openapi.json  
Request Signing guide: https://api.confidentcannabis.com/v0/docs/request-signing.md