Integration GuidesGuide
Partner API integration guide
Architecture, authentication, scopes, ordering, results, events and retries for a partner integration.
On this page
Architecture
Your server → Partner API (bearer key, scope, Program grant)
→ canonical Solia order → laboratory transport → LIS/LIMS
→ released result → Partner API read + signed webhookCall 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}(scopesubjects:write). - Check
POST /v1/serviceabilitybefore creating the order. - Create with
POST /v1/ordersand anIdempotency-Key; cancel withPOST /v1/orders/{orderId}/cancelwhile cancellation is still possible. - Read
GET /v1/orders/{orderId}/exceptionsfor 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-Keyon order creation and reuse it when retrying the same request. - Retry only transient failures —
429 rate_limited,500 server_errorand network timeouts — with exponential backoff.503 not_configuredmeans the laboratory has not configured a required capability; do not retry it blindly. - Do not retry
400,401,403,404,409or422unchanged; fix the request. - Log the
request_idfrom 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.