Partner API integration guide

Your server → Partner API (bearer key, scope, Program grant)
  → canonical Solia order → laboratory transport → LIS/LIMS
  → released result → Partner API read + signed webhook

Call the Partner API only from your server. Keys must never reach a browser or mobile client.

Send Authorization: Bearer <key> on every request. Canonical scopes: programs:read, catalog:read, serviceability:read, subjects:write, orders:write, orders:read, orders:cancel, results:read, events:read, webhooks:manage. Request only the scopes your workflow uses; a missing scope returns 403 forbidden.

Access is per Program. Read GET /v1/programs, then GET /v1/programs/{programId}/catalog and GET /v1/programs/{programId}/requirements. Cache Catalog briefly; the laboratory can pause or archive items at any time.

• Optionally register your opaque subject with PUT /v1/subjects/{externalSubjectId} (scope subjects:write).
• Check POST /v1/serviceability before creating the order.
• Create with POST /v1/orders and an Idempotency-Key; cancel with POST /v1/orders/{orderId}/cancel while cancellation is still possible.
• Read GET /v1/orders/{orderId}/exceptions for specimen, sample and result exceptions.

Use webhooks as a signal and the API as the source of truth: on result.* events, re-read GET /v1/orders/{orderId}/results. Use GET /v1/events to recover from any missed delivery.

• Always send Idempotency-Key on order creation and reuse it when retrying the same request.
• Retry only transient failures — 429 rate_limited, 500 server_error and network timeouts — with exponential backoff. 503 not_configured means the laboratory has not configured a required capability; do not retry it blindly.
• Do not retry 400, 401, 403, 404, 409 or 422 unchanged; fix the request.
• Log the request_id from every response for support.

Only the key, the webhook secret and the Program identifiers change. See Sandbox to Production for what carries forward.