Matrix Sciences Customer Portal API

Integrate laboratory sample tracking and test results with your own systems. This v1 collection includes read requests for samples and results, plus a proposed contract for creating submissions with individual samples and composites.

API reference

Request	Method	Purpose	Contract status
samples-v1	GET	Retrieve a page of sample records and their status.	Documented from saved responses.
results-v1	GET	Retrieve a page of laboratory test results.	Documented from saved responses.
submission-v1	POST	Create a submission containing samples and optional composites.	Draft; route and backend behavior are not verified.

Quick start

Select the sbx-v1 environment for sandbox work, or prod-v1 for production access.
Obtain the environment URL, endpoint paths, and API token from your Matrix Sciences integration contact. The supplied environment files intentionally leave these values empty.
Populate the variables below. Keep the token in your private environment values.
Open samples-v1, set a date range appropriate to your data, and send page 1.
Inspect the samples array and hasNextPage. Continue through subsequent pages as described below, then use results-v1 to retrieve test results.

Variable	Value to supply
`baseUrl`	Assigned HTTPS API base URL, without a trailing slash.
`samples`	Samples endpoint path relative to `baseUrl`, without a leading slash.
`results`	Results endpoint path relative to `baseUrl`, without a leading slash.
`submission`	Submission endpoint path, once the draft route is confirmed.
`api_token`	API credential for the selected environment.

Each request resolves to {{baseUrl}}/{{endpoint}}, using the corresponding path variable. Sandbox and production values must be configured separately; no hostname or route is implied by the variable names.

Authentication

The collection sends the token as the api_token query parameter:

JavaScript

Python

Java

cURL

Shell

{{baseUrl}}/{{samples}}?api_token={{api_token}}&page=1

Use HTTPS and keep token values out of shared examples, published documentation, and URL logs. The saved submission request uses the same parameter as a draft configuration; its final authentication contract remains to be confirmed.

Filtering and pagination

Both GET requests include page, sample_id, sample_submission_id, start_date, and end_date. Their request pages document each parameter. Saved requests start at page 1 and leave identifier filters blank.

Responses contain a string-valued page, a boolean hasNextPage, and either a samples or results array. Start with page 1; when hasNextPage is true, request the next page with the same filters. Stop when it is false. Do not infer completion from an array length: page size, maximum page number, and ordering guarantees are not specified.

Date filters use YYYY-MM-DD. The filtered date field, timezone, boundary inclusivity, and rules for combining filters are not established by the saved responses. Confirm those details before using date windows for incremental synchronization.

Data conventions

Concept	Convention
Identifiers	Treat identifiers as opaque strings, including numeric-looking catalog IDs.
Read response timestamps	Saved GET responses use display strings such as `Aug 19, 2026 6:30 pm`, without a timezone offset. Do not assume UTC.
Submission collection dates	The draft request uses `YYYY-MM-DD` with no time component.
Submission timestamp	The draft creation response uses a top-level ISO 8601 UTC `submitted_at`, such as `2026-09-30T17:00:00Z`.
Empty values	Saved GET responses contain empty strings. The draft POST supports omission or `null` for documented optional nullable properties.
Test results	`result` is a string; values may be numeric text or qualitative text.
Response content	Saved GET bodies contain JSON, although their recorded media type is `text/plain;charset=utf-8`. Parse accordingly.

Keep identifiers distinct

sample_id: the downstream sample identifier returned by read requests.
sample_submission_id: a sample-submission row identifier; the saved samples response includes empty values.
submission_id: the parent submission identifier in the draft creation response.
client_submission_ref: your correlation reference for a submission.
client_sample_ref: your correlation reference for an individual sample or composite, unique across both arrays within one submission.
line_number: the application’s display position, which can change when rows are edited. It is not a permanent identifier.

The draft create response does not return sample_id. Do not substitute a client reference or parent submission identifier for a read filter.

Examples and contract coverage

Saved GET examples are compact, synthetic illustrations of the recorded response structure. The POST request and 201 Created example illustrate the proposed submission contract. Example catalog selections must be checked against the lists supplied for your customer, division, and laboratory.

This reference documents the fields visible in those examples; it does not establish complete enums or guarantee that every field is always populated. No live endpoint validation was performed for this documentation.

Troubleshooting

Symptom	Check
Unresolved variables or an invalid URL	Select an environment and populate `baseUrl` and the relevant endpoint path.
Authentication failure	Check that `api_token` is populated privately and belongs to the selected environment.
Unexpected or empty read results	Check the date range, identifier filters, and page number; confirm filter semantics with your integration contact.
Response parser rejects the GET body	The recorded content type is plain text even though the body contains JSON.
Submission validation failure	Check client references, catalog values, composite membership, and the draft field rules on submission-v1.

Error status codes and response schemas, rate limits, and retry timing have not been specified. Treat non-success responses separately from the documented success payloads. A client_submission_ref provides correlation only: duplicate-request handling and idempotency are undefined, so reconcile an uncertain POST outcome before retrying.