Working with Sandbox

Simulate the full kit journey in sandbox - either by driving lifecycle events directly with the simulate endpoint, or by walking the realistic supplier flow with kit activation - then fetch and acknow

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.

The simulate endpoint exists only outside production - calling it in production returns 403.

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

payment_complete → processing → delivery_fulfilled → kit_activated → sample_processing_in_lab → results_ready

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:

Sandbox

{
  "event_type": "order.status_changed",
  "event_id": "249956485092777984",
  "timestamp": 1763661470,
  "data": {
    "order_id": "251285377984405504",
    "status": "order.delivery_fulfilled",
    "supplier_item_id": "249602021676720128",
    "tracking_number": "KnD3d5PMZyq5ulNcWkrq"
  }
}

Production

{
  "event_type": "order.status_changed",
  "event_id": "249956485092777984",
  "timestamp": 1763661470,
  "data": {
    "order_id": "251285377984405504",
    "status": "order.delivery_fulfilled",
    "tracking_number": "KnD3d5PMZyq5ulNcWkrq"
  }
}

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:

https://vantage-sandbox.tryterra.co/api/v1/orders/activate?kit_id=249602021676720128

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:

Lab processing

{
  "event_type": "order_item.results_status_change",
  "event_id": "249958648347009024",
  "timestamp": 1763661985,
  "data": {
    "order_id": "251285377984405504",
    "order_item_id": "251285377984405507",
    "results_status": "results.sample_processing_in_lab",
    "variant_id": "100041",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]"
    }
  }
}

Results ready

{
  "event_type": "order_item.results_status_change",
  "event_id": "249958796259139584",
  "timestamp": 1763662021,
  "data": {
    "order_id": "251285377984405504",
    "order_item_id": "251285377984405507",
    "results_status": "results.results_ready",
    "variant_id": "100041",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "first_name": "John",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone_number": "[phone]"
    }
  }
}

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):

cURL

curl 'https://vantage-sandbox.tryterra.co/api/v1/results/251285377984405507?test_taker_id=257837964552478720' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Python

import requests

order_item_id = "251285377984405507"
test_taker_id = "257837964552478720"
url = f"https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}"

response = requests.get(
    url,
    auth=("YOUR_DEV_ID", "YOUR_API_KEY"),
    params={"test_taker_id": test_taker_id},
)
print(response.text)

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	orderItemID := "251285377984405507"
	testTakerID := "257837964552478720"
	url := fmt.Sprintf(
		"https://vantage-sandbox.tryterra.co/api/v1/results/%s?test_taker_id=%s",
		orderItemID, testTakerID,
	)

	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth("YOUR_DEV_ID", "YOUR_API_KEY")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, err := io.ReadAll(res.Body)
	if err != nil {
		panic(err)
	}
	fmt.Println(string(body))
}

200

{
  "download_url": "https://storage.googleapis.com/.../normalised.json?X-Goog-Signature=...",
  "format": "json",
  "expires_at": "2025-11-19T19:08:04.400Z"
}

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):

curl --request POST \
  'https://vantage-sandbox.tryterra.co/api/v1/results/251285377984405507/acknowledge?test_taker_id=257837964552478720' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

{ "status": "acknowledged" }

Acknowledgment is a mandatory compliance step with liability consequences, and it must be triggered by an explicit end-user action - never automatically. Read Acknowledging Results before building this flow.