Test Registrations

Test registrations can be looked up by their UUID, TRF code (e.g. LML-AB1234), or your own foreign ID if you set one. All {id} parameters accept any of these identifiers.

Create a test registration

POST /api/test_registration/

Register a test directly without creating an order. This is useful for GPs and doctors integrating with their own systems.

Request body

Field	Type	Required	Description
`patient_id`	string	Yes	UUID of the patient
`product_ids`	array	One of	Array of product UUIDs to include
`product_skus`	array	One of	Array of product SKUs (alternative to `product_ids`)
`biomarker_codes`	array	No	Array of specific biomarker codes to test
`foreign_id`	string	No	Your own external reference ID for future lookups

Example request

curl -X POST "https://api.londonmedicallaboratory.co.uk/api/test_registration/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "a1b2c3d4-...",
    "product_ids": ["e5f6a7b8-..."],
    "foreign_id": "YOUR-INTERNAL-REF-123"
}'

Example response

Returns 201 Created:

{
    "id": "f8a9b0c1-...",
    "trf_code": "LML-AB1234",
    "short_code": "AB1234",
    "status": "awaiting_patient",
    "results_ready": false,
    "patient_id": "a1b2c3d4-...",
    "product_ids": ["e5f6a7b8-..."],
    "product_skus": ["LML-THY-ADV"],
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane@example.com",
    "date_of_birth": "1990-05-15",
    "gender": "female",
    "ethnicity": null,
    "created_at": "2024-03-15",
    "completed_at": null,
    "patient_registered_at": null,
    "foreign_id": "YOUR-INTERNAL-REF-123",
    "lab_id": null,
    "parent_id": null,
    "uk_address": null,
    "doctors_note": null,
    "doctors_name": null,
    "download_url": null,
    "appointment_id": null,
    "clinical_details": null
}

Get a test registration

GET /api/test_registration/{id}

Retrieve a single test registration. The {id} parameter accepts a UUID, TRF code, or foreign ID.

List test registrations

GET /api/test_registration/

Returns a paginated list of test registrations for your brand.

Update a test registration

PATCH /api/test_registration/{id}

Assign a patient to a test registration, or update its external reference. This is how you register a patient through your own site after creating an order.

Request body

Field	Type	Required	Description
`patient_id`	string	Yes	UUID of the patient to assign
`mobile_phone_number`	string	No	Patient's mobile number for SMS result delivery
`foreign_id`	string	No	Your own external reference ID for future lookups

Example request

curl -X PATCH "https://api.londonmedicallaboratory.co.uk/api/test_registration/f8a9b0c1-..." \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "patient_id": "a1b2c3d4-...",
    "mobile_phone_number": "+447700900000"
}'

Get lab results

GET /api/test_registration/{id}/lab_results

Retrieve the lab results for a test registration. Returns 204 No Content if results are not yet available.

Example response

{
    "nr_of_results": 3,
    "current_page": 1,
    "nr_of_pages": 1,
    "results_per_page": 100,
    "next_page": null,
    "items": [
        {
            "id": "c1d2e3f4-...",
            "name": "Thyroid Stimulating Hormone (TSH)",
            "code": "TSH",
            "value": "2.5",
            "min_range": "0.27",
            "max_range": "4.2",
            "unit_type": "mIU/L",
            "out_of_range": null,
            "successful": true,
            "status": "success",
            "biomarker_id": "b1c2d3e4-...",
            "comment": null,
            "human_readable_value": "2.5 mIU/L",
            "error_reason": null,
            "fallback_range_applied": false
        }
    ]
}

Result fields

Field	Type	Description
`value`	string\|null	The test result value
`min_range` / `max_range`	string\|null	Normal reference range for this biomarker
`unit_type`	string\|null	Unit of measurement (e.g. `mIU/L`, `mmol/L`)
`out_of_range`	string\|null	`high`, `low`, or `null` if within range
`status`	string	`pending`, `success`, or `failed`
`successful`	boolean	Whether the test was processed successfully
`error_reason`	string\|null	Reason for failure if `status` is `failed`

Download results PDF

GET /api/test_registration/{id}/download_pdf

Download the lab results as a PDF document. Returns 404 if the patient has not yet been assigned.

Force a retest

POST /api/test_registration/{id}/retest

Create a retest for a test registration that has failed results. A new order and test registration will be created. Returns 201 Created with the new test registration, or 400 if there are no failed results or no linked order.

Send completion email

POST /api/test_registration/{id}/send-complete-email

Send the test registration completion email to a specific email address. The patient must not have been assigned yet.

Field	Type	Required	Description
`email`	string	Yes	Email address to send the completion email to

Sub-resources

Each test registration has related resources available as separate endpoints.

Method	Endpoint	Description
`GET`	`/api/test_registration/{id}/lab_results`	Get lab results (paginated)
`GET`	`/api/test_registration/{id}/products`	Get products included in this test
`GET`	`/api/test_registration/{id}/order`	Get the linked order
`GET`	`/api/test_registration/{id}/patient`	Get the assigned patient
`GET`	`/api/test_registration/{id}/appointment`	Get the linked appointment
`GET`	`/api/test_registration/{id}/lml_lab_id`	Get the LIMS lab ID
`GET`	`/api/test_registration/{id}/download_pdf`	Download results as PDF
`GET`	`/api/test_registration/barcode/{barcode}`	Look up by barcode / order number