⌘K

Integration GuidesGuide

Partner API integration guide

Architecture, authentication, scopes, ordering, results, events and retries for a partner integration.

On this page

Architecture

text
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.

Authentication and scopes

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

Programs and Catalog

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.

Ordering

  • 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.

Results and events

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.

Idempotency and retries

  • 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.

Sandbox to Production

Your integration code and endpoint paths can carry forward. Production requires separately authorized Programs and grants, credentials, webhook subscriptions and signing secrets, laboratory adapters, endpoints and validation. Production promotion is currently paused; Sandbox success is not authorization.

Related resources