> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.one.mtxsci.com/ms-cp-customer-api/introduction/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.one.mtxsci.com/_mcp/server. # Introduction # 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 1. Select the `sbx-v1` environment for sandbox work, or `prod-v1` for production access. 2. Obtain the environment URL, endpoint paths, and API token from your Matrix Sciences integration contact. The supplied environment files intentionally leave these values empty. 3. Populate the variables below. Keep the token in your private environment values. 4. Open **samples-v1**, set a date range appropriate to your data, and send page `1`. 5. 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 ```javascript {{baseUrl}}/{{samples}}?api_token={{api_token}}&page=1 ``` #### Python ```python {{baseUrl}}/{{samples}}?api_token={{api_token}}&page=1 ``` #### Java ```java {{baseUrl}}/{{samples}}?api_token={{api_token}}&page=1 ``` #### cURL ```curl {{baseUrl}}/{{samples}}?api_token={{api_token}}&page=1 ``` #### Shell ```bash {{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.