Working with Sandbox

To familiarise yourself with the API, we provide a comprehensive sandbox environment where you can simulate ordering kits from different suppliers
Below we will simulate an ordering a kit + end user's flow from a supplier that supports a 2 step activation process

Kit Activation in Sandbox

Certain suppliers require end-users to activate the kit themselves (i.e scanning a QR code on the kit).

For Sandbox you will have to mimic this step by calling the api/v1/orders/activate endpoint (as shown below)

You will receive automated webhooks in sandbox to your configured endpoint

1. Order a test kit

Follow the steps as outlined in Ordering your first test within the sandbox

2. Receiving supplier's item ID

After ordering a kit you should receive the following webhook:
Notice how supplier_item_id is only available when working in sandbox

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

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

3. Activating the kit

For suppliers who support 2 step activation, on each kit there will be a QR code that embeds the following URL which links to prod
To simulate scanning the QR code:
- Replace the production domain with sandbox domain
- Paste supplier_item_id as the query parameter

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

You should be redirected to the page below - fill out the details and activate your kit!

4. Lab received kit + results

4. Lab received kit + Results

At this point your end user will take the test and post it to the lab to be analysed. Upon arriving at the lab, a webhook will be sent to you.
Results will be available shortly after arrival of the kit at the lab, with a second webhook sent.
To simulate this, the sandbox environment automatically sends the following two webhooks after successful kit activation, sent at 1-2 minute intervals.
N.B There is also a change you will get a results.sample_rejected webhook

{
  "data": {
    "order_id": 249956252111773696,
    "order_item_id": 249956252111773699,
    "results_status": "results.sample_processing_in_lab",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "country_code": 1,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": 4155551234
    },
    "variant_id": 100021
  },
  "event_id": 249958648347009024,
  "event_type": "order_item.results_status_change",
  "timestamp": 1763661985
}

{
  "data": {
    "order_id": 249956252111773696,
    "order_item_id": 249956252111773699,
    "results_status": "results.results_ready",
    "test_taker": {
      "test_taker_id": "257837964552478720",
      "country_code": 1,
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Doe",
      "phone_number": 4155551234
    },
    "variant_id": 100021
  },
  "event_id": 249958796259139584,
  "event_type": "order_item.results_status_change",
  "timestamp": 1763662021
}

5. Fetching results

When fetching results, a pre-signed URL will be returned which can be used to download test results
Use order_item_id and test_taker_id to fetch results

curl --location --request GET \
  'https://vantage-sandbox.tryterra.co/api/v1/results/249956252111773699?test_taker_id=257837964552478720' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>'

import requests

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

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>'
}

response = requests.get(url, headers=headers)

print(response.text)
print(response.status_code)

package main

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

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

	client := &http.Client{}
	req, err := http.NewRequest("GET", url, nil)
	if err != nil {
		panic(err)
	}

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>")

	res, err := client.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))
}

{
    "download_url": "https://storage.googleapis.com/terra-diagnostics-results-sandbox-terra-diagnostics-sandbox/client/terra-client-payable/results/249717507/normalised.json?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=terra-diagnostics-sa%40terra-diagnostics-sandbox.iam.gserviceaccount.com%2F20251119%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20251119T185304Z&X-Goog-Expires=899&X-Goog-Signature=c3d7b929233b6e08bd41d8f9959950736db897226b99014e2f10238185851f6fe2191d5c8e34a518a6325c21ff7c627a1a6753e5f3b4e52d219e3107be9c6feaa0362eb442a5766404bdab19bbb53c408584e15e68f00b1099dd71f6a82282ba3d970917562583a589aceca7d20599f4215874d3af9853661c6d31bc52407bdf59287415b162860b691e39fbf13f9e5a18768279cc8c318ea79383a6315ebaabec814f097a83c8102657a47d20f00c0dcac3152eb62f86c40190053824206bb21b27c01febf818a02aec1587de2770881f332c5e688d55f169ef61e7f15708963681a27665805863e313aa9fce39d3201177&X-Goog-SignedHeaders=host",
    "format": "json",
    "expires_at": "2025-11-19T19:08:04.40025031Z"
}

6. Acknowledge Results

Once an end user sees their results, they are required to acknowledge it
- How an end-user interfaces with the acknowledgement page must adhere to Acknowledging Results to be compliant
Importantly you need to inform us an end-user has acknowledged their results by hitting the following endpoint
- We also use order_item_id and test_taker_id to acknowledge
- https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}/acknowledge?test_taker_id={test_taker_id}

curl --location --request POST \
  'https://vantage-sandbox.tryterra.co/api/v1/results/249956252111773699/acknowledge?test_taker_id=257837964552478720' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>'

import requests

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

headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>'
}

response = requests.post(url, headers=headers)

print(response.text)
print(response.status_code)

package main

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

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

	client := &http.Client{}
	req, err := http.NewRequest("POST", url, nil)
	if err != nil {
		panic(err)
	}

	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("Authorization", "Basic <YOUR_CLIENT_ID:YOUR_CLIENT_SECRET_BASE64>")

	res, err := client.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))
}

PreviousOrdering your first test NextWebhooks

Last updated 12 days ago

Was this helpful?