Working with Sandbox

The sandbox environment (https://vantage-sandbox.tryterra.co) lets you exercise the entire integration - ordering, fulfilment webhooks, kit activation, results, and acknowledgment - without shipping a physical kit. Webhooks are delivered to your configured endpoint exactly as in production.

There are two ways to move a sandbox order through its lifecycle:

1. The simulate endpoint - drive any lifecycle event on demand. Deterministic, scriptable, ideal for automated tests.

2. The simulated supplier flow - the sandbox supplier automatically progresses your order on timers, including the end-user kit-activation step. Ideal for experiencing the realistic journey.

Both start the same way: place an order as shown in Ordering your first test.

Option 1: The simulate endpoint

POST /api/v1/orders/{orderID}/simulate applies one lifecycle event to your order exactly as a real supplier update would: the status history is recorded and the corresponding signed webhook is delivered to your registered endpoint.

curl --request POST \
  'https://vantage-sandbox.tryterra.co/api/v1/orders/251285377984405504/simulate' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{ "event": "delivery_fulfilled" }'

{ "order_id": "251285377984405504", "applied_event": "delivery_fulfilled" }

• event is one of: payment_complete, payment_failed, processing, delayed, cancelled, delivery_fulfilled, completed (order events), kit_activated, sample_processing_in_lab, sample_rejected, partial_results_ready, results_ready, lab_processing_error, escalation_raised (result events).

• Result events target an order item; pass "order_item_id" to pick one when the order has several.

• Only valid forward transitions are accepted - an out-of-order event returns 422 (see the lifecycle graphs in Core concepts).

• results_ready also stores a sample result document, so the download and acknowledge flows below work end to end.

A minimal happy path for a fresh AT_HOME order (which starts at order.payment_processing):

then fetch and acknowledge the result (steps 4-5 below).

Option 2: The simulated supplier flow

The sandbox supplier automatically progresses orders the way a real kit journey would:

1. Shipping

Within a minute or so of placing the order you receive order.status_changed webhooks, ending with order.delivery_fulfilled carrying a tracking number and - sandbox only - the supplier_item_id you'll need for activation:

2. Kit activation (end-user step)

Some suppliers require the end user to activate their kit before the lab will process it - typically by scanning a QR code on the packaging that opens an activation page. To stand in for your end user scanning the QR code, open the activation URL in a browser, using the supplier_item_id from the webhook above as kit_id:

Fill out the test-taker details on the page and activate the kit. A successful activation:

• emits a results.kit_activated webhook containing the newly assigned test_taker_id - capture it, you need it to fetch and acknowledge results;

• moves the order item to results.kit_activated.

(In production the QR code embeds the same URL on vantage.tryterra.co; the browser visit is only a sandbox stand-in for the scan. Activation can also be performed programmatically - POST /api/v1/orders/activate - if you build your own activation UI.)

3. Lab processing and results

After activation, the sandbox automatically sends the remaining result webhooks at 1-2 minute intervals:

The sandbox happy path delivers results.results_ready; use the simulate endpoint (Option 1) to exercise results.sample_rejected and the other failure paths deliberately.

4. Fetching results

Fetch a presigned download URL with the order_item_id and the test_taker_id (both required):

The download_url is valid for 15 minutes. Re-call this endpoint to mint a fresh URL rather than storing it. The downloaded document is a FHIR Bundle - see Results.

5. Acknowledge the results

After your end user has actually viewed their results, record their confirmation (again with both order_item_id and test_taker_id):