{ "openapi": "3.1.0", "info": { "title": "Solia Partner API", "version": "v1", "description": "Server-to-server API for ordering laboratory diagnostics, tracking order\nlifecycle and retrieving released results.\n\nAuthentication: send your API key as `Authorization: Bearer `.\nKeys are environment-bound and scope-bound; a sandbox key can never reach\nproduction data.\n\nWebhook delivery semantics:\n- Delivery is at-least-once: the same event may arrive more than once.\n- Events may arrive out of order; use `sequence` from GET /v1/events to order them.\n- Subscribers must be idempotent on `event_id` and ignore a delivery id already seen.\n- Verify the HMAC-SHA256 signature over `.` before parsing.\n- Reject a delivery whose timestamp is outside a 5 minute tolerance.\n- The Partner API is authoritative: reconcile with GET /v1/events after any gap.\n\nWebhook events versus the authoritative API:\n- A webhook event carries identifiers and coarse state only. Analyte values, patient demographics, report documents, headers and secrets are never present.\n- The authoritative state is always the API: GET /v1/orders/{orderId}/results for released structured results, and GET /v1/orders/{orderId}/results/{resultId} for one version.\n- Deliveries are at-least-once and may arrive out of order. Deduplicate on event_id and treat the highest released result version from the API as current.\n- A missed or failed delivery never loses data: replay the ordered stream from GET /v1/events using the cursor, then re-read the results endpoint.\n- result.partial and result.final describe the same append-only lineage; a partial version remains retrievable after the final version is released.\n- result.corrected signals a new superseding version. The prior version is retained and reported as superseded rather than removed.\n- result.critical is an escalation signal only. Retrieve the critical workflow state and the observations from the result endpoint.\n- A report document is retrieved per request through the governed report endpoint. No permanent or signed document URL is ever delivered in an event." }, "servers": [], "security": [ { "PartnerApiKey": [] } ], "tags": [ { "name": "Health" }, { "name": "Laboratory" }, { "name": "Locations" }, { "name": "Programs" }, { "name": "Serviceability" }, { "name": "Subjects" }, { "name": "Orders" }, { "name": "Results" }, { "name": "Events" }, { "name": "Sandbox" } ], "paths": { "/v1/health": { "get": { "tags": [ "Health" ], "summary": "Verify credentials and environment", "responses": { "200": { "description": "The key is valid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string" }, "version": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "server_time": { "type": "string", "format": "date-time" } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "401": { "description": "Missing or invalid key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/lab": { "get": { "tags": [ "Laboratory" ], "summary": "Retrieve the laboratory capability profile", "description": "Canonical, non-secret capability truth for the laboratory this key belongs to. Certification identifiers (CLIA, CAP) are not modeled in Solia today and are therefore reported as `not_modeled` rather than claimed, and the identity state is a laboratory self-declaration, never a verification.", "responses": { "200": { "description": "The capability profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/LabCapability" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "403": { "description": "The key lacks `catalog:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/locations": { "get": { "tags": [ "Locations" ], "summary": "List externally serviceable collection locations", "description": "Only active locations in the service geography of the active programs this key is granted, in the current environment. Street address, telephone and internal operational detail are never returned.", "responses": { "200": { "description": "Serviceable locations.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Location" } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "403": { "description": "The key lacks `serviceability:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs": { "get": { "tags": [ "Programs" ], "summary": "List programs this key may order from", "responses": { "200": { "description": "Granted programs.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Program" } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "403": { "description": "The key lacks `programs:read`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs/{programId}": { "get": { "tags": [ "Programs" ], "summary": "Retrieve one program", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The program.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Program" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "Unknown or ungranted program.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/programs/{programId}/catalog": { "get": { "tags": [ "Programs" ], "summary": "List orderable tests in a program", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Orderable tests.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/serviceability": { "post": { "tags": [ "Serviceability" ], "summary": "Check whether a location and test can be fulfilled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "program_id", "item_id" ], "properties": { "program_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "region": { "type": "string", "maxLength": 80 }, "collection": { "type": "string", "maxLength": 40 } } }, "example": { "program_id": "…", "item_id": "…", "region": "CA", "collection": "Mobile" } } } }, "responses": { "200": { "description": "Serviceability decision.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "serviceable": { "type": "boolean" }, "reasons": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/subjects/{externalSubjectId}": { "put": { "tags": [ "Subjects" ], "summary": "Register or update your opaque subject reference", "description": "Send only your own opaque identifier. Do not send names, dates of birth or clinical detail.", "parameters": [ { "name": "externalSubjectId", "in": "path", "required": true, "schema": { "type": "string", "maxLength": 190 } } ], "responses": { "200": { "description": "The subject link.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "external_subject_id": { "type": "string" }, "linked": { "type": "boolean" } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/programs/{programId}/requirements": { "get": { "tags": [ "Programs" ], "summary": "Discover what an order must carry", "description": "Reports the laboratory's governed ordering requirements. A facet the laboratory has not configured is reported as `not_configured` and requires nothing.", "parameters": [ { "name": "programId", "in": "path", "required": true, "description": "Program identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "item_id", "in": "query", "schema": { "type": "string", "format": "uuid" } }, { "name": "region", "in": "query", "schema": { "type": "string", "maxLength": 80 } } ], "responses": { "200": { "description": "The governed requirement profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/OrderRequirements" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "Unknown program for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/sandbox/order-fixtures": { "get": { "tags": [ "Sandbox" ], "summary": "List synthetic order-request fixtures", "description": "Clearly synthetic request templates for the minimal, provider, patient and ask-at-order-entry contracts. Never real data.", "responses": { "200": { "description": "Synthetic fixtures.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "type": "object" } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/orders": { "post": { "tags": [ "Orders" ], "summary": "Create an order", "description": "Send `Idempotency-Key`; a repeat with the same key returns the same order.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 190 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "external_order_id", "program_id", "item_id", "external_subject_id", "collection" ], "properties": { "external_order_id": { "type": "string", "maxLength": 190 }, "program_id": { "type": "string", "format": "uuid" }, "item_id": { "type": "string", "format": "uuid" }, "external_subject_id": { "type": "string", "maxLength": 190 }, "collection": { "type": "string", "maxLength": 40 }, "region": { "type": "string", "maxLength": 80 }, "patient": { "$ref": "#/components/schemas/PatientInput" }, "ordering_provider": { "$ref": "#/components/schemas/ProviderInput" }, "aoe_answers": { "type": "array", "items": { "$ref": "#/components/schemas/AoeAnswer" } }, "clinical_notes": { "type": "string", "maxLength": 2000 }, "billing_mode": { "type": "string", "maxLength": 40 }, "requested_collection_at": { "type": "string", "format": "date-time" }, "collection_location": { "type": "string", "maxLength": 190 } } } } } }, "responses": { "201": { "description": "The created order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "409": { "description": "The idempotency key was reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "422": { "description": "The program, test or subject is not orderable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } }, "429": { "description": "Rate limited; honour `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}": { "get": { "tags": [ "Orders" ], "summary": "Retrieve order status", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "Unknown order for this key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/cancel": { "post": { "tags": [ "Orders" ], "summary": "Cancel an order while cancellation is still possible", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The cancelled order.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Order" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "409": { "description": "The order has progressed too far to cancel.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/results": { "get": { "tags": [ "Results" ], "summary": "Retrieve released structured results", "description": "Released results only. An unreleased or in-progress result version is reported as pending and is never returned, whatever its internal status. Versions are append-only: a partial version stays retrievable after the final version is released, and a corrected or amended version supersedes rather than replaces the version before it. `version_lineage` states the current authoritative version and every superseded version. Observation values, units and reference intervals are exactly as the laboratory supplied them; LOINC is reported as `not_modeled` because Core holds no observation-level LOINC authority, and no code is ever derived.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Released results, if any.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "pending": { "type": "boolean" }, "pending_reason": { "type": [ "string", "null" ] }, "current_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "current_version": { "type": [ "integer", "null" ] }, "version_lineage": { "type": "array", "items": { "$ref": "#/components/schemas/ResultVersion" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/orders/{orderId}/results/{resultId}": { "get": { "tags": [ "Results" ], "summary": "Retrieve one released result version in full", "description": "The same released-only boundary as the collection endpoint. An unreleased version is reported as not found rather than acknowledged.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "resultId", "in": "path", "required": true, "description": "Released result version identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "The released result version.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "$ref": "#/components/schemas/Result" }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "No released result version with this identifier.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/results/{resultId}/report": { "get": { "tags": [ "Results" ], "summary": "Retrieve the governed laboratory report for a released result", "description": "Authorization is identical to the result itself: the same key, client, Program, environment, order and released version. Retrieval is always server-authorized per request — there is no permanent public link, no signed document URL, and no document URL is ever placed in a webhook delivery or a log. When no canonical laboratory report document exists the response is an explicit refusal carrying `report_not_modeled`; a report is never fabricated.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } }, { "name": "resultId", "in": "path", "required": true, "description": "Released result version identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Report availability and a short-lived, server-authorized retrieval path.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "result_id": { "type": "string", "format": "uuid" }, "report": { "$ref": "#/components/schemas/ReportAvailability" } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "404": { "description": "The result is not released, or no canonical report document exists for it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } }, "/v1/orders/{orderId}/exceptions": { "get": { "tags": [ "Orders" ], "summary": "Read canonical specimen, sample and result exceptions", "description": "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.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Canonical exceptions for this order, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "count": { "type": "integer" }, "action_required": { "type": "boolean" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/OrderException" } } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/events": { "get": { "tags": [ "Events" ], "summary": "Read the event stream for reconciliation", "parameters": [ { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } } ], "responses": { "200": { "description": "Events after the cursor, oldest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/sandbox/scenarios": { "get": { "tags": [ "Sandbox" ], "summary": "List deterministic sandbox scenarios", "responses": { "200": { "description": "Available scenarios.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "scenario": { "type": "string", "enum": [ "happy_path", "partial_then_final", "specimen_rejection_recollection", "critical_result", "transmission_failure_then_retry", "corrected_result", "webhook_failure_then_replay", "specimen_rejected" ] }, "steps": { "type": "integer" }, "events": { "type": "array", "items": { "type": "string", "enum": [ "order.created", "order.updated", "order.cancelled", "specimen.updated", "result.partial", "result.final", "result.corrected", "result.critical", "integration.action_required" ] } } } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } } } } }, "/v1/sandbox/orders/{orderId}/simulate": { "post": { "tags": [ "Sandbox" ], "summary": "Advance a synthetic sandbox order through a scenario", "description": "Sandbox only. A production key or a non-synthetic order is refused.", "parameters": [ { "name": "orderId", "in": "path", "required": true, "description": "Sandbox order identifier.", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": "string", "enum": [ "happy_path", "partial_then_final", "specimen_rejection_recollection", "critical_result", "transmission_failure_then_retry", "corrected_result", "webhook_failure_then_replay", "specimen_rejected" ] } } } } } }, "responses": { "200": { "description": "Applied steps.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "request_id" ], "properties": { "data": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "scenario": { "type": "string" }, "events_emitted": { "type": "integer" } } }, "request_id": { "type": "string" }, "cursor": { "type": [ "string", "null" ] } } } } } }, "422": { "description": "Simulation is not permitted for this key or order.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorEnvelope" } } } } } } } }, "webhooks": { "order.created": { "post": { "summary": "Delivery of order.created", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "order.updated": { "post": { "summary": "Delivery of order.updated", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "order.cancelled": { "post": { "summary": "Delivery of order.cancelled", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "specimen.updated": { "post": { "summary": "Delivery of specimen.updated", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.partial": { "post": { "summary": "Delivery of result.partial", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.final": { "post": { "summary": "Delivery of result.final", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.corrected": { "post": { "summary": "Delivery of result.corrected", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "result.critical": { "post": { "summary": "Delivery of result.critical", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } }, "integration.action_required": { "post": { "summary": "Delivery of integration.action_required", "description": "Verify `x-solia-signature` (HMAC-SHA256 over `.`) before parsing, and reject a timestamp older than five minutes. Respond 2xx quickly; retries follow 1m, 5m, 30m, 2h, 12h, 24h.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Acknowledged." } } } } }, "components": { "securitySchemes": { "PartnerApiKey": { "type": "http", "scheme": "bearer", "description": "Scopes: programs:read, catalog:read, serviceability:read, subjects:write, orders:write, orders:read, orders:cancel, results:read, events:read, webhooks:manage." } }, "schemas": { "ErrorEnvelope": { "type": "object", "required": [ "error", "request_id" ], "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "string" } } } }, "request_id": { "type": "string" } } }, "Program": { "type": "object", "properties": { "program_id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "status": { "type": "string" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "currency": { "type": [ "string", "null" ] } } }, "CatalogItem": { "type": "object", "description": "Canonical item identity and laboratory-native identity are distinct and both returned, together with mapping and orderable version provenance.", "properties": { "item_id": { "type": "string", "format": "uuid" }, "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid", "description": "Populated only when exactly one active orderable is mapped; null for a multi-orderable panel — see provenance.mapped_orderables." }, "lab_test_code": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "external_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "kind": { "type": [ "string", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "container": { "type": [ "string", "null" ] }, "min_volume_ml": { "type": [ "number", "null" ] }, "collection_methods": { "type": "array", "items": { "type": "string" } }, "preparation": { "type": [ "string", "null" ] }, "collection_instructions": { "type": "array", "description": "Supplied collection-method instructions. Distinct from specimen handling; empty when the laboratory supplied none.", "items": { "type": "object", "properties": { "method": { "type": "string" }, "instruction": { "type": "string" } } } }, "handling": { "type": [ "string", "null" ] }, "turnaround": { "type": [ "string", "null" ] }, "regions": { "type": "array", "items": { "type": "string" } }, "availability": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "currency": { "type": [ "string", "null" ] }, "price_visibility": { "type": "string", "enum": [ "visible", "hidden" ] }, "loinc": { "$ref": "#/components/schemas/TerminologyCode" }, "cpt": { "$ref": "#/components/schemas/TerminologyCode" }, "biomarkers": { "type": "array", "items": { "type": "string" } }, "markers": { "type": "array", "items": { "$ref": "#/components/schemas/Marker" } }, "aoe_requirement_refs": { "type": "array", "description": "Always empty: Solia has no canonical ask-at-order-entry storage yet. Generic clinical requirements are never relabelled as AOE.", "items": { "type": "string" } }, "mapping_version": { "type": [ "integer", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "status": { "type": [ "string", "null" ] }, "provenance": { "type": "object", "properties": { "item_id": { "type": "string", "format": "uuid" }, "mapping_version": { "type": [ "integer", "null" ] }, "mapping_status": { "type": [ "string", "null" ] }, "mapping_validation_status": { "type": [ "string", "null" ] }, "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid" }, "lab_test_code": { "type": [ "string", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "mapped_orderables": { "type": "array", "description": "Every active governed mapping entry in canonical position order. A panel legitimately maps to several laboratory orderables.", "items": { "$ref": "#/components/schemas/MappedOrderable" } } } } } }, "LabCapability": { "type": "object", "properties": { "laboratory_id": { "type": [ "string", "null" ], "format": "uuid" }, "display_name": { "type": [ "string", "null" ] }, "legal_name": { "type": [ "string", "null" ] }, "operating_name": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "certifications": { "type": "object", "description": "Not modeled canonically; no identifier is ever fabricated.", "properties": { "state": { "type": "string", "enum": [ "not_modeled" ] }, "identifiers": { "type": "array", "items": { "type": "string" } } } }, "jurisdictions": { "type": "array", "items": { "type": "string" } }, "service_geography": { "type": "array", "items": { "type": "string" } }, "collection_methods": { "type": "array", "description": "Collection-method keys only.", "items": { "type": "string" } }, "collection_modes": { "type": "array", "description": "Collection-mode keys only; a distinct canonical concept.", "items": { "type": "string" } }, "specimen_categories": { "type": "array", "items": { "type": "string" } }, "coding_systems_supplied": { "type": "array", "items": { "type": "string" } }, "reference_range_source": { "type": [ "string", "null" ] }, "standard_turnaround": { "type": [ "string", "null" ] }, "clinical_ordering_model": { "type": [ "string", "null" ] }, "laboratory_identity_state": { "type": "string", "description": "What the laboratory declared about itself. A self-declaration only — Solia stores no verification, accreditation or certification evidence.", "enum": [ "declared_laboratory", "declared_not_laboratory", "not_evaluated" ] } } }, "Location": { "type": "object", "properties": { "location_id": { "type": [ "string", "null" ], "format": "uuid" }, "location_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "timezone": { "type": [ "string", "null" ] }, "collection_methods": { "type": "array", "items": { "type": "string" } }, "appointment_required": { "type": [ "boolean", "null" ] }, "walk_in_allowed": { "type": [ "boolean", "null" ] }, "service_status": { "type": "string", "description": "Only serviceable locations are returned; inactive ones are omitted.", "enum": [ "active" ] } } }, "MappedOrderable": { "type": "object", "properties": { "lab_orderable_id": { "type": [ "string", "null" ], "format": "uuid" }, "lab_test_code": { "type": [ "string", "null" ] }, "panel_role": { "type": [ "string", "null" ] }, "is_required": { "type": [ "boolean", "null" ] }, "position": { "type": [ "integer", "null" ] }, "orderable_version": { "type": [ "integer", "null" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "container": { "type": [ "string", "null" ] }, "min_volume_ml": { "type": [ "number", "null" ] }, "preparation": { "type": [ "string", "null" ] }, "handling": { "type": [ "string", "null" ] }, "turnaround": { "type": [ "string", "null" ] }, "regions": { "type": "array", "items": { "type": "string" } } } }, "TerminologyCode": { "type": "object", "description": "A code is only `mapped` when a governed mapping exists.", "properties": { "system": { "type": "string", "enum": [ "LOINC", "CPT" ] }, "code": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "mapped", "unmapped", "not_supplied" ] } } }, "Marker": { "type": "object", "properties": { "marker_id": { "type": [ "string", "null" ], "format": "uuid" }, "canonical_key": { "type": [ "string", "null" ] }, "lab_marker_code": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "loinc": { "$ref": "#/components/schemas/TerminologyCode" }, "unit": { "type": [ "string", "null" ] }, "reference_range": { "type": [ "object", "null" ], "description": "Only supplied ranges are returned; none is ever inferred." }, "specimen_class": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "approved", "mapped", "unmapped", "not_supplied" ] } } }, "Order": { "type": "object", "properties": { "order_id": { "type": "string", "format": "uuid" }, "external_order_id": { "type": [ "string", "null" ] }, "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "lifecycle": { "type": "string" }, "next_action": { "type": [ "string", "null" ] }, "lifecycle_detail": { "type": "string", "enum": [ "accepted", "requisition_created", "collection_scheduled", "sample_collected", "sample_in_transit", "sample_received", "processing", "partial_results", "final_results", "sample_error", "recollection_required", "cancelled", "action_required" ] }, "requisition": { "type": "object", "properties": { "state": { "type": [ "string", "null" ] }, "requisition_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "laboratory_reference": { "type": [ "string", "null" ] }, "document": { "type": "object", "description": "No canonical requisition document generator exists today.", "properties": { "state": { "type": "string", "enum": [ "not_modeled" ] } } } } }, "accession": { "type": [ "object", "null" ], "properties": { "accession_number": { "type": [ "string", "null" ] }, "accessioned_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "source_system": { "type": [ "string", "null" ] } } }, "specimens": { "type": "array", "description": "Specimen identifiers and states only; never patient identity.", "items": { "type": "object", "properties": { "specimen_id": { "type": [ "string", "null" ], "format": "uuid" }, "specimen_code": { "type": [ "string", "null" ] }, "specimen_type": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "accession_number": { "type": [ "string", "null" ] }, "rejection_reason": { "type": [ "string", "null" ] }, "recollection_of": { "type": [ "string", "null" ], "format": "uuid" } } } }, "transmission": { "type": [ "object", "null" ], "properties": { "status": { "type": [ "string", "null" ] }, "attempt_no": { "type": [ "integer", "null" ] }, "sent_at": { "type": [ "string", "null" ], "format": "date-time" }, "ack_status": { "type": [ "string", "null" ] }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "external_order_ref": { "type": [ "string", "null" ] } } } } }, "PatientInput": { "type": "object", "description": "Sent only when the governed requirement profile asks for it. Written to the canonical subject record; never echoed in events or logs.", "properties": { "legal_first_name": { "type": "string", "maxLength": 120 }, "legal_last_name": { "type": "string", "maxLength": 120 }, "date_of_birth": { "type": "string", "format": "date" }, "sex_at_birth": { "type": "string", "maxLength": 40 }, "phone": { "type": "string", "maxLength": 40 }, "email": { "type": "string", "maxLength": 190 }, "region": { "type": "string", "maxLength": 80 }, "address_line1": { "type": "string", "maxLength": 190 }, "address_line2": { "type": "string", "maxLength": 190 }, "city": { "type": "string", "maxLength": 120 }, "postal_code": { "type": "string", "maxLength": 40 }, "country": { "type": "string", "maxLength": 80 } } }, "ProviderInput": { "type": "object", "description": "Either a canonical provider reference, or a name and NPI to resolve or register. Provider licences and jurisdictions are NOT modelled canonically, so none is accepted, validated or stored.", "properties": { "provider_reference": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 190 }, "npi": { "type": "string", "maxLength": 20 } } }, "AoeAnswer": { "type": "object", "required": [ "question_key", "answer" ], "description": "Answers your laboratory's own governed ask-at-order-entry questions. An answer to a question the laboratory does not define is refused.", "properties": { "question_key": { "type": "string", "maxLength": 120 }, "answer": { "type": "string", "maxLength": 500 } } }, "OrderRequirements": { "type": "object", "description": "Governed ordering requirements. `authority_state: not_configured` means the laboratory has configured no requirement for that facet, so it requires nothing; `not_modeled` means canonical Core carries no authority for that fact at all.", "properties": { "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "item_id": { "type": [ "string", "null" ], "format": "uuid" }, "jurisdiction": { "type": [ "string", "null" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "subject": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "opaque_reference", "identified" ] }, "required_patient_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "order": { "type": "object", "properties": { "required_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "provider": { "type": "object", "properties": { "requirement": { "type": "string", "enum": [ "not_required", "reference_required", "identified_required" ] }, "required_fields": { "type": "array", "items": { "type": "string" } }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] }, "license_authority_state": { "type": "string", "enum": [ "not_modeled" ] } } }, "aoe": { "type": "object", "properties": { "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] }, "questions": { "type": "array", "items": { "type": "object", "properties": { "question_key": { "type": "string" }, "prompt": { "type": [ "string", "null" ] }, "answer_type": { "type": "string", "enum": [ "text", "number", "boolean", "date", "choice" ] }, "options": { "type": "array", "items": { "type": "string" } }, "required": { "type": "boolean" }, "version": { "type": [ "integer", "null" ] } } } } } }, "clinical": { "type": "object", "properties": { "policy": { "type": "string" }, "ordering_model": { "type": [ "string", "null" ] }, "clinical_review": { "type": [ "string", "null" ] }, "intake_required": { "type": [ "boolean", "null" ] }, "requirement_id": { "type": [ "string", "null" ], "format": "uuid" }, "requirement_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } }, "collection": { "type": "object", "properties": { "methods": { "type": "array", "items": { "type": "string" } }, "regions": { "type": "array", "items": { "type": "string" } } } }, "billing": { "type": "object", "properties": { "mode_required": { "type": "boolean" }, "authority_state": { "type": "string", "enum": [ "configured", "not_configured" ] } } } } }, "Observation": { "type": "object", "description": "Exactly what the laboratory supplied, plus canonical mapping state. Values, units and reference intervals are never converted unless Core recorded a validated normalization, and `interpretation` normalizes only the laboratory's own flag.", "properties": { "observation_id": { "type": [ "string", "null" ], "format": "uuid" }, "canonical_biomarker_id": { "type": [ "string", "null" ] }, "biomarker_key": { "type": [ "string", "null" ] }, "lab_analyte_code": { "type": [ "string", "null" ] }, "terminology": { "type": "object", "properties": { "loinc": { "type": "object", "description": "Reported only as the laboratory supplied it. `not_modeled` means no code was supplied; a code is never derived.", "properties": { "system": { "type": "string", "enum": [ "LOINC" ] }, "code": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "not_modeled", "supplied_by_laboratory" ] } } }, "snomed": { "type": "object", "description": "Supplied-only qualitative terminology. Never derived.", "properties": { "system": { "type": "string", "enum": [ "SNOMED-CT" ] }, "code": { "type": [ "string", "null" ] }, "mapping_state": { "type": "string", "enum": [ "not_modeled", "supplied_by_laboratory" ] } } } } }, "method": { "type": [ "string", "null" ] }, "observation_status": { "type": [ "string", "null" ] }, "display_name": { "type": [ "string", "null" ] }, "health_area": { "type": [ "string", "null" ] }, "result_type": { "type": "string", "enum": [ "numeric", "qualitative", "text", "not_supplied" ] }, "value_numeric": { "type": [ "number", "null" ] }, "value_qualitative": { "type": [ "string", "null" ] }, "value_text": { "type": [ "string", "null" ] }, "source_value": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "source_unit": { "type": [ "string", "null" ] }, "normalized": { "type": [ "object", "null" ], "description": "Present only when Core applied a validated conversion.", "properties": { "value": { "type": [ "number", "null" ] }, "unit": { "type": [ "string", "null" ] }, "method": { "type": "string" } } }, "mapping_state": { "type": [ "string", "null" ] }, "reference_low": { "type": [ "number", "null" ] }, "reference_high": { "type": [ "number", "null" ] }, "reference_text": { "type": [ "string", "null" ] }, "lab_flag": { "type": [ "string", "null" ] }, "interpretation": { "type": "string", "enum": [ "normal", "low", "high", "critical_low", "critical_high", "abnormal", "not_supplied", "unmapped" ] }, "is_critical": { "type": "boolean" }, "observed_at": { "type": [ "string", "null" ], "format": "date-time" }, "position": { "type": [ "integer", "null" ] } } }, "ResultVersion": { "type": "object", "description": "Append-only lineage entry. A superseded version is retained, never destroyed.", "properties": { "result_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "version_type": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "partial", "final", "corrected", "amended" ] }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "supersedes_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "superseded_by_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "is_current": { "type": "boolean" } } }, "ReportAvailability": { "type": "object", "description": "Availability and an authenticated relative path only — never a signed or permanent document URL.", "properties": { "available": { "type": "boolean" }, "state": { "type": "string", "enum": [ "available", "not_available" ] }, "reason": { "type": [ "string", "null" ] }, "retrieval_path": { "type": [ "string", "null" ] } } }, "OrderException": { "type": "object", "description": "Canonical exception category with laboratory-native provenance. No free text.", "properties": { "exception_id": { "type": [ "string", "null" ], "format": "uuid" }, "category": { "type": "string", "enum": [ "specimen_rejected", "recollection_required", "collection_failed", "accession_missing", "transmission_failed", "acknowledgement_missing", "result_unmatched", "result_unknown", "result_normalization_failed", "catalog_mapping_required", "notification_failed", "provider_blocked", "critical_hold", "release_blocked", "other" ] }, "severity": { "type": [ "string", "null" ] }, "status": { "type": [ "string", "null" ] }, "retryable": { "type": [ "boolean", "null" ] }, "owner_role": { "type": [ "string", "null" ] }, "entity_type": { "type": [ "string", "null" ] }, "opened_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "source": { "type": "object", "properties": { "exception_type": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "adapter_key": { "type": [ "string", "null" ] } } } } }, "Result": { "type": "object", "description": "One RELEASED result version with normalized observations. Critical state is only what the laboratory or the governed protocol declared; Solia adds no medical interpretation.", "properties": { "result_id": { "type": [ "string", "null" ], "format": "uuid" }, "order_id": { "type": [ "string", "null" ], "format": "uuid" }, "accession_id": { "type": [ "string", "null" ], "format": "uuid" }, "accession_number": { "type": [ "string", "null" ] }, "panel_item_id": { "type": [ "string", "null" ], "format": "uuid" }, "version": { "type": [ "integer", "null" ] }, "version_type": { "type": [ "string", "null" ] }, "state": { "type": "string", "enum": [ "partial", "final", "corrected", "amended" ] }, "status": { "type": "string", "enum": [ "released", "not_released" ] }, "performing_laboratory": { "type": [ "string", "null" ] }, "performing_laboratory_system": { "type": [ "string", "null" ] }, "source_result_id": { "type": [ "string", "null" ] }, "source_provenance": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ], "format": "date-time" }, "received_at": { "type": [ "string", "null" ], "format": "date-time" }, "resulted_at": { "type": [ "string", "null" ], "format": "date-time" }, "released_at": { "type": [ "string", "null" ], "format": "date-time" }, "supersedes_result_id": { "type": [ "string", "null" ], "format": "uuid" }, "completeness": { "type": [ "object", "null" ], "properties": { "state": { "type": [ "string", "null" ] }, "expected_count": { "type": [ "integer", "null" ] }, "received_count": { "type": [ "integer", "null" ] }, "unresolved_count": { "type": [ "integer", "null" ] }, "missing_biomarker_keys": { "type": "array", "items": { "type": "string" } } } }, "critical": { "type": "object", "properties": { "is_critical": { "type": "boolean" }, "workflow_status": { "type": [ "string", "null" ] }, "acknowledgement_state": { "type": [ "string", "null" ] }, "escalation_state": { "type": [ "string", "null" ] }, "responsible_role": { "type": [ "string", "null" ] }, "notified_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "action_required": { "type": "boolean" } } }, "report": { "$ref": "#/components/schemas/ReportAvailability" }, "observation_count": { "type": "integer" }, "observations": { "type": "array", "items": { "$ref": "#/components/schemas/Observation" } } } }, "Event": { "type": "object", "properties": { "event_id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "order.created", "order.updated", "order.cancelled", "specimen.updated", "result.partial", "result.final", "result.corrected", "result.critical", "integration.action_required" ] }, "version": { "type": "integer" }, "occurred_at": { "type": "string", "format": "date-time" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "program_id": { "type": [ "string", "null" ], "format": "uuid" }, "data": { "type": "object", "description": "Identifiers and coarse state only — never values or demographics." } } } } } }