submission-v1 | Matrix Sciences FSQ API

Create a submission — draft

Create one submission containing individual samples and optional composites. Each composite has its own fields and tests and refers to individual samples by their client references.

Request: POST {{baseUrl}}/{{submission}}
Proposed success: 201 Created
Headers: Content-Type: application/json and Accept: application/json
Query: api_token={{api_token}} is the collection’s draft authentication configuration.

Before you submit

Obtain the lab enum and applicable product, site, and test catalogs for your customer context. The request’s lab, customer, division, and catalog values are illustrative selections. Replace them with authorized values before sending.

Submission fields

Field	Type	Requirement	Description
`client_submission_ref`	String	Required	Nonempty client correlation reference, echoed unchanged. Does not provide idempotency.
`customer`	String	Context required, proposed	Customer display name in this draft; resolve within the caller’s authorized scope.
`division`	String	Context required, proposed	Division display name in this draft; resolve within the caller’s authorized scope.
`requested_by`	String or null	Caller-derived, proposed	`null` proposes deriving the requester from the authenticated caller. Arbitrary caller identities require authorization.
`lab`	String	Required, proposed	Exact value from the lab enum supplied to the customer.
`po_number`	String or null	Optional	Purchase order reference; preserve leading zeros.
`submission_type`	String	Required	Exactly `Product` or `Environmental`.
`additional_info`	String or null	Optional	Submission-level information.
`special_instructions`	String or null	Optional	Submission-level instructions.
`samples`	Array of objects	At least one, proposed	Individual samples, declared once each.
`composites`	Array of objects	Optional, proposed	Composite definitions; omit or supply an empty array when none are needed.

Sample and composite fields

These fields apply to each object in both samples and composites. Composite values are independent of the values on their members.

Field	Type	Requirement	Description
`client_sample_ref`	String	Required	Nonempty reference, unique across both arrays within this submission.
`description`	String or null	Unconfirmed	Description of this individual sample or composite.
`product_id`	String	Required for samples; proposed for composites	Product ID from the applicable product catalog.
`product_desc`	String or null	Unconfirmed	Product description. Read responses use `product_description` instead.
`lot`	String or null	Unconfirmed	Lot reference, preserved as text.
`collection_date`	String or null	Unconfirmed	Date in `YYYY-MM-DD` format, without an inferred timezone.
`request_number`	String or null	Unconfirmed	Client request reference, distinct from a generated submission identifier.
`site_id`	String or null	Optional	Site catalog ID, not its name. Preserve numeric-looking IDs as strings, such as `"4"`.
`emp_zone`	Integer or null	Optional	EMP zone; allowed integers are unconfirmed. Omit or use `null` when blank.
`tests`	Array of objects	Minimum count unconfirmed	Tests for this row’s material. Each entry uses `test_code`.
`tests[].test_code`	String	Required per test, proposed	Exact test catalog Code, such as `LSP-VID-ENV`, rather than its description.
`client_sample_refs`	Array of strings	Required for composites, proposed	Composite-only membership list, referencing `samples[].client_sample_ref`.

Optional nullable fields may be omitted or sent as null under this draft. A nullable example does not settle whether a field marked unconfirmed may be omitted.

Environmental site and zone behavior

site_id and emp_zone are optional for both submission types. For an Environmental row with a supplied site_id and omitted or null emp_zone, the application looks up the zone from that site’s existing information. A composite uses its own site; its zone is not inferred from its members. Neither field becomes required when no site is supplied.

Composite membership and tests

Declare each individual sample once in samples.
Each composite has its own unique client_sample_ref and a nonempty client_sample_refs membership list under the proposed validation rules.
Members must reference individual samples in this request. Missing references, self references, composite references, and duplicate members within one composite are rejected by the proposed rules.
A sample may belong to several composites. The saved request has C1 referencing S1–S4, and C2 referencing S1 and S2.
Composite tests apply to the combined material independently of tests on individual samples and other composites. Do not copy them onto constituents.
The minimum physical constituent count beyond one, repeat-test rules, and valid composite/test combinations remain unconfirmed.

Ordering and correlation

Individual samples are created in their array order before composites are created, so membership references can resolve. The application then places composites first and renumbers all rows while preserving the relative order within each array.

The saved request therefore produces the intended final order:

Final line	Client reference	Row type
1	`C1`	Composite
2	`C2`	Composite
3	`S1`	Individual sample
4	`S2`	Individual sample
5	`S3`	Individual sample
6	`S4`	Individual sample

Without composites, sample line numbers start at 1. The intended 201 response is returned only after all rows, memberships, and application renumbering are complete; its line numbers must match stored and displayed order. Later edits can change line numbers, so correlate using client references and permanent row identifiers.

Success response — 201 Created

Field	Type	Description
`client_submission_ref`	String	Exact echo of the request’s correlation reference.
`submission_id`	String	Server-generated parent identifier. Its relationship to the displayed Sample Request ID is unconfirmed.
`submitted_at`	String	Required, non-null submission time in ISO 8601 UTC format: `YYYY-MM-DDTHH:mm:ssZ`. Top-level and response-only.
`samples`	Array of objects	Every created composite and individual sample exactly once, in final line-number order.
`samples[].client_sample_ref`	String	Exact echo of the row’s client reference.
`samples[].sample_submission_id`	String	Permanent generated row identifier, distinct from downstream `sample_id`. Composite record creation remains to be verified.
`samples[].line_number`	Integer	Final consecutive application position, starting at `1`.

Open the attached 201 Created example for the full mapping of four samples and two composites. Shared members appear only once in the response and do not result in multiple samples created in the application, regardless of how many composites reference them.

Validation and retry considerations

rush is unsupported in v1. Do not send server-generated IDs, line_number, or submitted_at in the request. Catalog selections must be validated in the applicable customer, division, and lab context.

Query parameters

api_tokenstringOptional

Request

This endpoint expects an object.

client_submission_refstringRequired

customerstringRequired

divisionstringRequired

labstringRequired

submission_typestringRequired

sampleslist of objectsRequired

compositeslist of objectsRequired

requested_byanyOptional

po_numberanyOptional

additional_infoanyOptional

special_instructionsanyOptional

Response

Created

client_submission_refstring

submission_idstring

submitted_atdatetime

sampleslist of objects