API Reference

Identify this laboratory

Confirms which laboratory a token belongs to — useful as a first call when wiring up an integration.

Response

{
    "id": "...",
    "name": "Acme Labs"
}

List assigned requests

Paginated list of requests assigned to this laboratory. Always scoped to the token's own laboratory — there is no way to see another laboratory's requests.

Response

{
    "items": [
        {
            "id": "7d2e6b2a-...",
            "status": "submitted",
            "trackingNumber": "220926-0003",
            "createdAt": "2026-09-20T09:14:00+00:00",
            "labStatus": "in_testing",
            "templateId": "...",
            "templateName": "Dairy — Standard Panel",
            "companyId": "...",
            "companyName": "Acme Foods",
            "createdById": "...",
            "createdByFirstName": "Ana",
            "createdByLastName": "Petrović",
            "laboratoryId": "...",
            "laboratoryName": "Acme Labs",
            "fields": {}
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "perPage": 20,
        "lastPage": 1
    }
}

Get one request

Full detail for one request assigned to this laboratory — field values, samples (each with its own field values, self-describing with name/label/type), examinations, comments and documents. 404 if the request doesn't exist or isn't assigned to this laboratory.

Response

{
    "id": "7d2e6b2a-...",
    "status": "submitted",
    "trackingNumber": "220926-0003",
    "createdAt": "2026-09-20T09:14:00+00:00",
    "template": {
        "id": "...",
        "name": "Dairy — Standard Panel"
    },
    "company": {
        "id": "...",
        "name": "Acme Foods"
    },
    "createdBy": {
        "firstName": "Ana",
        "lastName": "Petrović"
    },
    "laboratory": {
        "id": "...",
        "name": "Acme Labs"
    },
    "labStatus": "in_testing",
    "fieldValues": [
        {
            "fieldId": "...",
            "name": "batch_number",
            "label": "Batch number",
            "type": "text",
            "isMultiple": false,
            "displayTemplate": null,
            "value": "B-2201"
        }
    ],
    "examinations": [
        {
            "examinationId": "...",
            "name": "Microbiological panel",
            "appliesToAll": true,
            "sampleIds": []
        }
    ],
    "samples": [
        {
            "id": "...",
            "name": "Gouda cheese, 3 kg block",
            "quantity": 3,
            "unit": "kg",
            "batchNumber": "B-2201",
            "productionDate": "2026-09-18T00:00:00+00:00",
            "expiryDate": "2026-12-18T00:00:00+00:00",
            "packagingType": "vacuum",
            "sampleType": "product",
            "resultStatus": "pending",
            "resultNote": null,
            "createdAt": "2026-09-20T09:14:00+00:00",
            "parentId": null,
            "subjectId": "...",
            "subjectName": "Gouda 48%",
            "subjectTypeId": "...",
            "subjectVersionId": "...",
            "lotId": null,
            "procurementId": null,
            "examinations": [],
            "values": []
        }
    ],
    "comments": [
        {
            "id": "...",
            "body": "Sample arrived slightly warm — noted, testing proceeding.",
            "createdAt": "2026-09-21T11:02:00+00:00",
            "authorId": null,
            "authorFirstName": null,
            "authorLastName": null,
            "laboratoryId": "...",
            "laboratoryName": "Acme Labs"
        }
    ],
    "documents": [
        {
            "id": "...",
            "originalFilename": "result-report.pdf",
            "mimeType": "application/pdf",
            "size": 184320,
            "createdAt": "2026-09-22T08:30:00+00:00",
            "authorId": null,
            "authorFirstName": null,
            "authorLastName": null,
            "laboratoryId": "...",
            "laboratoryName": "Acme Labs"
        }
    ]
}

Download a document

Streams the raw file for one document attached to the request. Response is the binary file itself (Content-Type and Content-Disposition set from the stored document), not JSON.

Response

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="result-report.pdf"

<binary file content>

Update lab status

Moves the request through the laboratory's own progress. Any of the four values can be set at any time — there's no enforced order. Setting done requires every sample to already have a result (not Pending) and locks the request: no further status changes, comments, or documents afterwards.

Request

{
    "labStatus": "in_testing"
}

Response

[]

Post a comment

Adds a comment to the request's conversation, attributed to this laboratory. This is the same thread visible on the request's dossier and the human Laboratory Portal.

Request

{
    "body": "Sample arrived slightly warm — noted, testing proceeding."
}

Response

{
    "id": "..."
}

Upload a result document

Attaches a result document to the request. multipart/form-data only, field name file. Only application/pdf is accepted — anything else is rejected before it touches storage.

Request

Content-Type: multipart/form-data; boundary=...

--...
Content-Disposition: form-data; name="file"; filename="result-report.pdf"
Content-Type: application/pdf

<binary file content>
--...--

Response

{
    "id": "..."
}