Quickstart

Laboratory setup is lab-first and has six steps: Laboratory information → Testing capabilities → Fulfillment → Test your setup → Connect your laboratory → Production readiness.

1. Laboratory information — create the account and workspace, then complete the laboratory profile.
2. Testing capabilities — add orderable tests, specimen, turnaround and laboratory code mappings in the Catalog.
3. Fulfillment — configure collection models, service geography and serviceable locations.
4. Test your setup — use synthetic Sandbox data to rehearse serviceability, ordering, specimen and result behavior.
5. Connect your laboratory — configure the HTTPS/JSON contract (the executable self-service path) or request a managed HL7 v2, FHIR or SFTP/file integration. A managed request is tracked but does not create a live interface; native transports are implemented but not enabled (see Connectivity status). A passing connection test proves reachability and authentication, not LIS acceptance of real orders.
6. Production readiness — complete technical readiness and Sandbox/integration testing at no charge. Production authorization is a separate, governed commercial step and is currently paused; native installations additionally require the evidence in Installation validation & go-live.

• Programs are not required to complete the core laboratory setup; they are configured when the laboratory offers testing through a partner or channel.
• Standard DTC and Solia On Demand are optional channels and are never required laboratory setup steps.
• Partner API client, credential and webhook configuration is a later operational workflow where a partner integration applies.

Activation preserves the completed six-step journey in the companion Sandbox and creates the live Production workspace. Production Partner API setup then becomes a separate post-live workflow.

Every key, record and event belongs to exactly one environment. Sandbox keys start with sk_sandbox and only reach synthetic Sandbox data; Production keys start with sk_live and are issued only after the laboratory is live. Build and test the whole workflow below in Sandbox first.

1. Create a workspace from Explore Sandbox, or ask the laboratory you integrate with to register your API client.
2. In Integrations → API clients the laboratory grants your client one or more Programs and issues a Sandbox key with the scopes you need.
3. Store the key in your server-side secret store. It is shown once.

export SOLIA_API_BASE="https://app.soliadirect.com/api/public/partner/v1"
export SOLIA_API_KEY="<sandbox key from the Control Plane>"

SOLIA_API_BASE already ends in the API version, so every path below starts after it ($SOLIA_API_BASE/health, never $SOLIA_API_BASE/v1/health). Later steps set PROGRAM_ID, ITEM_ID, REGION, COLLECTION, ORDER_ID and LAST_CURSOR from earlier responses.

curl -s "$SOLIA_API_BASE/health" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

A valid key returns its environment inside data and a request_id. An invalid, expired or revoked key returns 401 unauthorized; an inactive client or environment mismatch returns 403 forbidden.

See API Reference → api-reference/health for the full generated schema, statuses and errors.

curl -s "$SOLIA_API_BASE/programs" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Only granted Programs appear. An empty list means no grant exists in this environment yet — ask the laboratory to grant one; it is not an error.

curl -s "$SOLIA_API_BASE/programs/$PROGRAM_ID/catalog" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Keep the returned item identifier; orders reference it as item_id.

curl -s -X POST "$SOLIA_API_BASE/serviceability" \
  -H "Authorization: Bearer $SOLIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"program_id":"'"$PROGRAM_ID"'","item_id":"'"$ITEM_ID"'","region":"'"$REGION"'","collection":"'"$COLLECTION"'"}'

program_id and item_id are schema-required. Although region and collection are schema-optional, eligibility requires both; missing values return region_required or collection_required. Treat a not-serviceable or manual-review answer as final — do not reimplement clinical or jurisdiction rules client-side.

curl -s -X POST "$SOLIA_API_BASE/orders" \
  -H "Authorization: Bearer $SOLIA_API_KEY" \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{"external_order_id":"order-1001","program_id":"'"$PROGRAM_ID"'","item_id":"'"$ITEM_ID"'","external_subject_id":"subject-1001","collection":"'"$COLLECTION"'"}'

• Required fields: external_order_id, program_id, item_id, external_subject_id, collection. Add patient, provider or question answers only when the requirements response asks for them.
• Reusing an Idempotency-Key with the same body returns the original order; with a different body it returns 409 conflict.
• 422 unprocessable means the order failed governed requirements; 404 not_found can mean the Program is not granted to this key.

See API Reference → api-reference/orders for the full generated schema, statuses and errors.

curl -s -X POST "$SOLIA_API_BASE/sandbox/orders/$ORDER_ID/simulate" \
  -H "Authorization: Bearer $SOLIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scenario":"happy_path"}'

Available scenarios: happy_path, partial_then_final, specimen_rejection_recollection, critical_result, transmission_failure_then_retry, corrected_result, webhook_failure_then_replay, specimen_rejected.

curl -s "$SOLIA_API_BASE/orders/$ORDER_ID/results" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Only released versions are returned. Treat the highest released version as current and retrieve the governed report per request.

Register your public HTTPS endpoint for your client and environment (the laboratory can do this in Integrations → Webhooks, or an authorized Health Company member in the workspace), select event types and store the one-time signing secret securely. Verify every delivery as shown in Webhooks & event reconciliation.

curl -s "$SOLIA_API_BASE/events?limit=50&cursor=$LAST_CURSOR" \
  -H "Authorization: Bearer $SOLIA_API_KEY"

Persist next_cursor after each page. After any outage, replay from your last cursor, then re-read the affected orders and results.

After the laboratory activates, it grants your client a Production Program and issues a Production key with multi-factor step-up. Swap the key and webhook secret; your code and paths stay the same. Sandbox fixtures and simulation are not available in Production. See Sandbox to Production.

Start with the current authorized Sandbox Program/catalog and generated request examples. Do not send real laboratory traffic from a candidate profile: installed authority, vendor ACK/callback/finality, clinical review and separate launch approval remain prerequisites.