API Docs

Add a sample to an order

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

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.

Try it

Log in to send test requests to this endpoint straight from the docs.

Responses

200 Success
order object
Show 33 child attributes Hide 33 child attributes
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
Show 6 child attributes Hide 6 child attributes
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
Show 9 child attributes Hide 9 child attributes
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
Show 6 child attributes Hide 6 child attributes
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
Show 6 child attributes Hide 6 child attributes
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
Show 90 child attributes Hide 90 child attributes
id string

Sample ID

order_id string

Orders ID

client_id integer

Client ID

lab object

Lab

Show 2 child attributes Hide 2 child attributes
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
Show 4 child attributes Hide 4 child attributes
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
Show 3 child attributes Hide 3 child attributes
id integer

Unique ID for Test Type

name string

Test Type Name

abbreviation string

Test Type Abbreviation

cover_image object
Show 3 child attributes Hide 3 child attributes
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

Show 3 child attributes Hide 3 child attributes
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

Show 3 child attributes Hide 3 child attributes
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

Show 3 child attributes Hide 3 child attributes
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

Show 3 child attributes Hide 3 child attributes
filename string
public_key string (uuid)

Unique public key for file

url string

Public URL to access file

logs array of objects
Show 4 child attributes Hide 4 child attributes
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
Show 4 child attributes Hide 4 child attributes
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

Show 3 child attributes Hide 3 child attributes
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

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.

How to sign requests 
# 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
}'
Response · 200
{
  "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"
  }
}