Solia Direct DocsControl Plane
⌘K

API ReferenceReference

Orders endpoints

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

Machine-readable OpenAPI description

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

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": "string",
  "program_id": "1c9d5b70-3f42-4a51-8d0e-77b6c2419f83",
  "item_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
  "external_subject_id": "string",
  "collection": "string",
  "region": "string",
  "patient": {
    "legal_first_name": "string",
    "legal_last_name": "string",
    "date_of_birth": "string",
    "sex_at_birth": "string",
    "phone": "string",
    "email": "string",
    "region": "string",
    "address_line1": "string",
    "address_line2": "string",
    "city": "string",
    "postal_code": "string",
    "country": "string"
  },
  "ordering_provider": {
    "provider_reference": "1c9d5b70-3f42-4a51-8d0e-77b6c2419f83",
    "name": "string",
    "npi": "string"
  },
  "aoe_answers": [
    {
      "question_key": "string",
      "answer": "string"
    }
  ],
  "clinical_notes": "string",
  "billing_mode": "string",
  "requested_collection_at": "2026-01-15T14:32:07Z"
}

Responses

  • 201 — The created order.
  • 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.
json
{
  "data": {
    "order_id": "8f14e45f-ceea-4c2b-9b3f-2a1d0c7b6a11",
    "external_order_id": "string",
    "program_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
    "lifecycle": "string",
    "next_action": "string",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "string",
      "requisition_id": "string",
      "created_at": "2026-01-15T14:32:07Z",
      "laboratory_reference": "string",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "string",
      "accessioned_at": "2026-01-15T14:32:07Z",
      "received_at": "2026-01-15T14:32:07Z",
      "source_system": "string"
    },
    "specimens": [
      {
        "specimen_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
        "specimen_code": "string",
        "specimen_type": "string",
        "status": "string",
        "collected_at": "2026-01-15T14:32:07Z",
        "received_at": "2026-01-15T14:32:07Z",
        "accession_number": "string",
        "rejection_reason": "string",
        "recollection_of": "1c9d5b70-3f42-4a51-8d0e-77b6c2419f83"
      }
    ],
    "transmission": {
      "status": "string",
      "attempt_no": 1,
      "sent_at": "2026-01-15T14:32:07Z",
      "ack_status": "string",
      "acknowledged_at": "2026-01-15T14:32:07Z",
      "external_order_ref": "string"
    }
  },
  "request_id": "string",
  "cursor": "string"
}

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.

Responses

  • 200 — The order.
  • 404 — Unknown order for this key.
json
{
  "data": {
    "order_id": "8f14e45f-ceea-4c2b-9b3f-2a1d0c7b6a11",
    "external_order_id": "string",
    "program_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
    "lifecycle": "string",
    "next_action": "string",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "string",
      "requisition_id": "string",
      "created_at": "2026-01-15T14:32:07Z",
      "laboratory_reference": "string",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "string",
      "accessioned_at": "2026-01-15T14:32:07Z",
      "received_at": "2026-01-15T14:32:07Z",
      "source_system": "string"
    },
    "specimens": [
      {
        "specimen_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
        "specimen_code": "string",
        "specimen_type": "string",
        "status": "string",
        "collected_at": "2026-01-15T14:32:07Z",
        "received_at": "2026-01-15T14:32:07Z",
        "accession_number": "string",
        "rejection_reason": "string",
        "recollection_of": "1c9d5b70-3f42-4a51-8d0e-77b6c2419f83"
      }
    ],
    "transmission": {
      "status": "string",
      "attempt_no": 1,
      "sent_at": "2026-01-15T14:32:07Z",
      "ack_status": "string",
      "acknowledged_at": "2026-01-15T14:32:07Z",
      "external_order_ref": "string"
    }
  },
  "request_id": "string",
  "cursor": "string"
}

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.

Responses

  • 200 — The cancelled order.
  • 409 — The order has progressed too far to cancel.
json
{
  "data": {
    "order_id": "8f14e45f-ceea-4c2b-9b3f-2a1d0c7b6a11",
    "external_order_id": "string",
    "program_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
    "lifecycle": "string",
    "next_action": "string",
    "lifecycle_detail": "accepted",
    "requisition": {
      "state": "string",
      "requisition_id": "string",
      "created_at": "2026-01-15T14:32:07Z",
      "laboratory_reference": "string",
      "document": {
        "state": "not_modeled"
      }
    },
    "accession": {
      "accession_number": "string",
      "accessioned_at": "2026-01-15T14:32:07Z",
      "received_at": "2026-01-15T14:32:07Z",
      "source_system": "string"
    },
    "specimens": [
      {
        "specimen_id": "5b2f0a19-7c64-4c8e-9a12-6de4f0b31c57",
        "specimen_code": "string",
        "specimen_type": "string",
        "status": "string",
        "collected_at": "2026-01-15T14:32:07Z",
        "received_at": "2026-01-15T14:32:07Z",
        "accession_number": "string",
        "rejection_reason": "string",
        "recollection_of": "1c9d5b70-3f42-4a51-8d0e-77b6c2419f83"
      }
    ],
    "transmission": {
      "status": "string",
      "attempt_no": 1,
      "sent_at": "2026-01-15T14:32:07Z",
      "ack_status": "string",
      "acknowledged_at": "2026-01-15T14:32:07Z",
      "external_order_ref": "string"
    }
  },
  "request_id": "string",
  "cursor": "string"
}

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.

Responses

  • 200 — Canonical exceptions for this order, newest first.
json
{
  "data": {
    "order_id": "8f14e45f-ceea-4c2b-9b3f-2a1d0c7b6a11",
    "count": 1,
    "action_required": true,
    "exceptions": [
      {
        "exception_id": "8f14e45f-ceea-4c2b-9b3f-2a1d0c7b6a11",
        "category": "specimen_rejected",
        "severity": "string",
        "status": "string",
        "retryable": true,
        "owner_role": "string",
        "entity_type": "string",
        "opened_at": "2026-01-15T14:32:07Z",
        "resolved_at": "2026-01-15T14:32:07Z",
        "source": {
          "exception_type": null,
          "domain": null,
          "adapter_key": null
        }
      }
    ]
  },
  "request_id": "string",
  "cursor": "string"
}