ReferenceReference

Orders endpoints

Exact request and response contracts for the orders endpoints, generated from the enforced Partner API contract.

Machine-readable OpenAPI description

On this page

Endpoints in this group
POST /v1/orders
GET /v1/orders/{orderId}
POST /v1/orders/{orderId}/cancel
GET /v1/orders/{orderId}/exceptions

Endpoints in this group

POST/v1/ordersCreate an order

GET/v1/orders/{orderId}Retrieve order status

POST/v1/orders/{orderId}/cancelCancel an order while cancellation is still possible

GET/v1/orders/{orderId}/exceptionsRead canonical specimen, sample and result exceptions

Important

Base path: /api/public/partner/v1. Every response carries request_id; every failure uses the standard error envelope documented under Errors.

POST`/v1/orders`

Create an order

Send Idempotency-Key; a repeat with the same key returns the same order.

Authentication & scope

Authentication: Authorization: Bearer <API key>. The key is bound to one laboratory, one API client and one environment.
Required scope: orders:write. A key without it is refused with 403 forbidden.

Request headers

Idempotency-Key (required) — string

Request body

Required body fields: external_order_id, program_id, item_id, external_subject_id, collection.

json

{
  "external_order_id": "synthetic",
  "program_id": "00000000-0000-4000-8000-000000000001",
  "item_id": "00000000-0000-4000-8000-000000000001",
  "external_subject_id": "synthetic",
  "collection": "synthetic",
  "region": "synthetic",
  "patient": {
    "legal_first_name": "synthetic",
    "legal_last_name": "synthetic",
    "date_of_birth": "2000-01-01",
    "sex_at_birth": "synthetic",
    "phone": "synthetic",
    "email": "synthetic",
    "region": "synthetic",
    "address_line1": "synthetic",
    "address_line2": "synthetic",
    "city": "synthetic",
    "postal_code": "synthetic",
    "country": "synthetic"
  },
  "ordering_provider": {
    "provider_reference": "00000000-0000-4000-8000-000000000001",
    "name": "synthetic",
    "npi": "synthetic"
  },
  "aoe_answers": [
    {
      "question_key": "synthetic",
      "answer": "synthetic"
    }
  ],
  "clinical_notes": "synthetic",
  "billing_mode": "synthetic",
  "requested_collection_at": "2026-10-19T00:00:00Z",
  "collection_location": "synthetic"
}

Synthetic schema examples are illustrative, not eligible records. Set PROGRAM_ID and ITEM_ID from granted Programs/Catalog, ORDER_ID and RESULT_ID from current responses, and EXTERNAL_SUBJECT_ID to an opaque synthetic reference. Replace body identifiers with authorized records and include patient/provider/question fields only when current requirements request them. Use Sandbox; Production requires separate approval.

cURL

bash

curl -s -X POST "$SOLIA_API_BASE/orders" \
  -H "Authorization: Bearer $SOLIA_API_KEY" \
  -H "Idempotency-Key: request-1001" \
  -H "Content-Type: application/json" \
  -d '{"external_order_id":"synthetic","program_id":"00000000-0000-4000-8000-000000000001","item_id":"00000000-0000-4000-8000-000000000001","external_subject_id":"synthetic","collection":"synthetic","region":"synthetic","patient":{"legal_first_name":"synthetic","legal_last_name":"synthetic","date_of_birth":"2000-01-01","sex_at_birth":"synthetic","phone":"synthetic","email":"synthetic","region":"synthetic","address_line1":"synthetic","address_line2":"synthetic","city":"synthetic","postal_code":"synthetic","country":"synthetic"},"ordering_provider":{"provider_reference":"00000000-0000-4000-8000-000000000001","name":"synthetic","npi":"synthetic"},"aoe_answers":[{"question_key":"synthetic","answer":"synthetic"}],"clinical_notes":"synthetic","billing_mode":"synthetic","requested_collection_at":"2026-10-19T00:00:00Z","collection_location":"synthetic"}'

Responses

201 — The created order.
401 — Missing, invalid, revoked or expired key.
403 — Client, environment or scope denied.
409 — The idempotency key was reused with a different body.
422 — The program, test or subject is not orderable.
429 — Rate limited; honour Retry-After.
500 — Canonical request failed; reconcile uncertain actions.
503 — Required API configuration is unavailable.

json

{
  "data": {
    "order_id": "00000000-0000-4000-8000-000000000001",
    "external_order_id": "synthetic",
    "program_id": "00000000-0000-4000-8000-000000000001",
    "lifecycle": "synthetic",
    "next_action": "synthetic",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "synthetic",
      "requisition_id": "synthetic",
      "created_at": "2026-10-19T00:00:00Z",
      "laboratory_reference": "synthetic",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "synthetic",
      "accessioned_at": "2026-10-19T00:00:00Z",
      "received_at": "2026-10-19T00:00:00Z",
      "source_system": "synthetic"
    },
    "specimens": [
      {
        "specimen_id": "00000000-0000-4000-8000-000000000001",
        "specimen_code": "synthetic",
        "specimen_type": "synthetic",
        "status": "synthetic",
        "collected_at": "2026-10-19T00:00:00Z",
        "received_at": "2026-10-19T00:00:00Z",
        "accession_number": "synthetic",
        "rejection_reason": "synthetic",
        "recollection_of": "00000000-0000-4000-8000-000000000001"
      }
    ],
    "transmission": {
      "status": "synthetic",
      "attempt_no": 1,
      "sent_at": "2026-10-19T00:00:00Z",
      "ack_status": "synthetic",
      "acknowledged_at": "2026-10-19T00:00:00Z",
      "external_order_ref": "synthetic"
    }
  },
  "request_id": "synthetic"
}

Important

This endpoint accepts Idempotency-Key. Replaying the same key with the same body returns the original result; reusing it with a different body is refused with 409 conflict.

GET`/v1/orders/{orderId}`

Retrieve order status

Authentication & scope

Authentication: Authorization: Bearer <API key>. The key is bound to one laboratory, one API client and one environment.
Required scope: orders:read. A key without it is refused with 403 forbidden.

Path parameters

orderId (required) — string (uuid). Order identifier.

cURL

bash

curl -s "$SOLIA_API_BASE/orders/$ORDER_ID" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Responses

200 — The order.
401 — Missing, invalid, revoked or expired key.
403 — Client, environment or scope denied.
404 — Unknown order for this key.
429 — Per-instance client rate limit exceeded; honor Retry-After.
500 — Canonical request failed; reconcile uncertain actions.
503 — Required API configuration is unavailable.

json

{
  "data": {
    "order_id": "00000000-0000-4000-8000-000000000001",
    "external_order_id": "synthetic",
    "program_id": "00000000-0000-4000-8000-000000000001",
    "lifecycle": "synthetic",
    "next_action": "synthetic",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "synthetic",
      "requisition_id": "synthetic",
      "created_at": "2026-10-19T00:00:00Z",
      "laboratory_reference": "synthetic",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "synthetic",
      "accessioned_at": "2026-10-19T00:00:00Z",
      "received_at": "2026-10-19T00:00:00Z",
      "source_system": "synthetic"
    },
    "specimens": [
      {
        "specimen_id": "00000000-0000-4000-8000-000000000001",
        "specimen_code": "synthetic",
        "specimen_type": "synthetic",
        "status": "synthetic",
        "collected_at": "2026-10-19T00:00:00Z",
        "received_at": "2026-10-19T00:00:00Z",
        "accession_number": "synthetic",
        "rejection_reason": "synthetic",
        "recollection_of": "00000000-0000-4000-8000-000000000001"
      }
    ],
    "transmission": {
      "status": "synthetic",
      "attempt_no": 1,
      "sent_at": "2026-10-19T00:00:00Z",
      "ack_status": "synthetic",
      "acknowledged_at": "2026-10-19T00:00:00Z",
      "external_order_ref": "synthetic"
    }
  },
  "request_id": "synthetic"
}

POST`/v1/orders/{orderId}/cancel`

Cancel an order while cancellation is still possible

Authentication & scope

Authentication: Authorization: Bearer <API key>. The key is bound to one laboratory, one API client and one environment.
Required scope: orders:cancel. A key without it is refused with 403 forbidden.

Path parameters

orderId (required) — string (uuid). Order identifier.

cURL

bash

curl -s -X POST "$SOLIA_API_BASE/orders/$ORDER_ID/cancel" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Responses

200 — The cancelled order.
401 — Missing, invalid, revoked or expired key.
403 — Client, environment or scope denied.
409 — The order has progressed too far to cancel.
429 — Per-instance client rate limit exceeded; honor Retry-After.
500 — Canonical request failed; reconcile uncertain actions.
503 — Required API configuration is unavailable.

json

{
  "data": {
    "order_id": "00000000-0000-4000-8000-000000000001",
    "external_order_id": "synthetic",
    "program_id": "00000000-0000-4000-8000-000000000001",
    "lifecycle": "synthetic",
    "next_action": "synthetic",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "synthetic",
      "requisition_id": "synthetic",
      "created_at": "2026-10-19T00:00:00Z",
      "laboratory_reference": "synthetic",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "synthetic",
      "accessioned_at": "2026-10-19T00:00:00Z",
      "received_at": "2026-10-19T00:00:00Z",
      "source_system": "synthetic"
    },
    "specimens": [
      {
        "specimen_id": "00000000-0000-4000-8000-000000000001",
        "specimen_code": "synthetic",
        "specimen_type": "synthetic",
        "status": "synthetic",
        "collected_at": "2026-10-19T00:00:00Z",
        "received_at": "2026-10-19T00:00:00Z",
        "accession_number": "synthetic",
        "rejection_reason": "synthetic",
        "recollection_of": "00000000-0000-4000-8000-000000000001"
      }
    ],
    "transmission": {
      "status": "synthetic",
      "attempt_no": 1,
      "sent_at": "2026-10-19T00:00:00Z",
      "ack_status": "synthetic",
      "acknowledged_at": "2026-10-19T00:00:00Z",
      "external_order_ref": "synthetic"
    }
  },
  "request_id": "synthetic"
}

GET`/v1/orders/{orderId}/exceptions`

Read canonical specimen, sample and result exceptions

Normalized through the same canonical operational-exception architecture the laboratory operations surface uses — there is no second exception model. Structural fields only: operator notes, evidence and resolution text are never returned, and a laboratory-native vendor code is never guessed.

Authentication & scope

Authentication: Authorization: Bearer <API key>. The key is bound to one laboratory, one API client and one environment.
Required scope: orders:read. A key without it is refused with 403 forbidden.

Path parameters

orderId (required) — string (uuid). Order identifier.

cURL

bash

curl -s "$SOLIA_API_BASE/orders/$ORDER_ID/exceptions" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Responses

200 — Canonical exceptions for this order, newest first.
401 — Missing, invalid, revoked or expired key.
403 — Client, environment or scope denied.
429 — Per-instance client rate limit exceeded; honor Retry-After.
500 — Canonical request failed; reconcile uncertain actions.
503 — Required API configuration is unavailable.

json

{
  "data": {
    "order_id": "00000000-0000-4000-8000-000000000001",
    "count": 1,
    "action_required": true,
    "exceptions": [
      {
        "exception_id": "00000000-0000-4000-8000-000000000001",
        "category": "specimen_rejected",
        "severity": "synthetic",
        "status": "synthetic",
        "retryable": true,
        "owner_role": "synthetic",
        "entity_type": "synthetic",
        "opened_at": "2026-10-19T00:00:00Z",
        "resolved_at": "2026-10-19T00:00:00Z",
        "source": {
          "exception_type": "synthetic",
          "domain": "synthetic",
          "adapter_key": "synthetic"
        }
      }
    ]
  },
  "request_id": "synthetic"
}

Related resources

API Reference OpenAPI Specification Health

Endpoints in this group

POST/v1/orders

GET/v1/orders/{orderId}

POST/v1/orders/{orderId}/cancel

GET/v1/orders/{orderId}/exceptions

Related resources

POST`/v1/orders`

GET`/v1/orders/{orderId}`

POST`/v1/orders/{orderId}/cancel`

GET`/v1/orders/{orderId}/exceptions`