Ordering your first test

Place your first sandbox order in a few minutes: browse the catalog, order a test kit, and watch the fulfilment webhooks arrive.

Prerequisites: Vantage sandbox credentials and a configured webhook endpoint (Account setup and authentication). All examples below run against the sandbox.

Key terminology (full detail in Core concepts), with a consumer-electronics analogy:

• Product type: the broadest category of offering (e.g. iPhone, MacBook, iPad)

• Product: individual products within each type (e.g. iPhone 17 Pro, iPhone 16 Pro Max)

• Product variant: the specific configuration an end user receives (e.g. iPhone 17 White 256GB) - this is what you order

Production: https://vantage.tryterra.co | Sandbox: https://vantage-sandbox.tryterra.co

1. Explore product types

cURL

curl 'https://vantage-sandbox.tryterra.co/api/v1/products' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Python

import requests

url = "https://vantage-sandbox.tryterra.co/api/v1/products"
response = requests.get(url, auth=("YOUR_DEV_ID", "YOUR_API_KEY"))
print(response.text)

Go

package main

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

func main() {
    url := "https://vantage-sandbox.tryterra.co/api/v1/products"

    req, _ := http.NewRequest("GET", url, nil)
    req.SetBasicAuth("YOUR_DEV_ID", "YOUR_API_KEY")

    res, _ := http.DefaultClient.Do(req)
    defer res.Body.Close()

    body, _ := io.ReadAll(res.Body)
    fmt.Println(string(body))
}

200

[
  {
    "id": 1,
    "name": "Blood Test",
    "description": "Diagnostic blood panels and biomarker tests"
  }
]

2. Explore products within a product type

Suppose we want a blood test. 1 is the product type ID from the response above:

cURL

curl 'https://vantage-sandbox.tryterra.co/api/v1/products/1' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Python

import requests

product_type_id = 1
url = f"https://vantage-sandbox.tryterra.co/api/v1/products/{product_type_id}"
response = requests.get(url, auth=("YOUR_DEV_ID", "YOUR_API_KEY"))
print(response.text)

200

[
  {
    "id": 10002,
    "product_type_id": 1,
    "name": "Blood Test",
    "description": "At-home blood test kit with lab processing.",
    "base_price_cents": 4999,
    "currency": 840,
    "availability": 1
  }
]

3. Explore product variants

Now let's choose the exact blood test to order. 10002 is the product ID from the response above:

cURL

curl 'https://vantage-sandbox.tryterra.co/api/v1/products/10002/variants' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Python

import requests

product_id = 10002
url = f"https://vantage-sandbox.tryterra.co/api/v1/products/{product_id}/variants"
response = requests.get(url, auth=("YOUR_DEV_ID", "YOUR_API_KEY"))
print(response.text)

200

[
  {
    "id": 100041,
    "product_id": 10002,
    "product_type_id": 1,
    "variant_name": "Inflammation",
    "variant_defining_attrs": {
      "biomarkers": ["hs-CRP", "Vitamin D"],
      "panel": "Inflammation",
      "turnaround_days": "3-5"
    },
    "descriptive_attrs_override": {
      "notes": "Inflammation marker testing"
    },
    "variant_availability": 1,
    "price_cents": 7900,
    "currency": 840,
    "available_collection_types": ["AT_HOME", "GO_TO_LAB"]
  }
]

Check available_collection_types before offering a collection method to a user - not every variant supports both.

4. Order a test kit

Let's order one "Inflammation" kit (variant_id 100041) as an AT_HOME order:

• An order needs: your own client_order_reference_id, a collection_type, the recipient, an address, and the items (variant_id + quantity).

• AT_HOME orders take a shipping_address; GO_TO_LAB orders take a requested_lab_address instead - see Test Collection Methods.

• Prices are integer cents; currency is ISO 4217 numeric (840 = USD).

cURL

curl --request POST 'https://vantage-sandbox.tryterra.co/api/v1/orders' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "client_order_reference_id": "TEST-ORDER-001",
    "collection_type": "AT_HOME",
    "recipient": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "[phone]",
        "date_of_birth": "1995-10-10",
        "gender_at_birth": "male"
    },
    "shipping_address": {
        "address_line_1": "123 Market Street",
        "city": "San Francisco",
        "administrative_area": "CA",
        "country_code": "US",
        "postal_code": "94102"
    },
    "items": [
        {
            "variant_id": "100041",
            "quantity": 1
        }
    ]
}'

Python

import requests

url = "https://vantage-sandbox.tryterra.co/api/v1/orders"

payload = {
    "client_order_reference_id": "TEST-ORDER-001",
    "collection_type": "AT_HOME",
    "recipient": {
        "first_name": "John",
        "last_name": "Smith",
        "email": "[email protected]",
        "phone_number": "[phone]",
        "date_of_birth": "1995-10-10",
        "gender_at_birth": "male",
    },
    "shipping_address": {
        "address_line_1": "123 Market Street",
        "city": "San Francisco",
        "administrative_area": "CA",
        "country_code": "US",
        "postal_code": "94102",
    },
    "items": [
        {
            "variant_id": "100041",
            "quantity": 1,
        }
    ],
}

response = requests.post(url, auth=("YOUR_DEV_ID", "YOUR_API_KEY"), json=payload)
print(response.status_code)
print(response.text)

201

{
  "order_id": "251285377984405504",
  "recipient_id": "251285377984405505",
  "order_items": [
    {
      "order_id": "251285377984405504",
      "order_item_id": "251285377984405507",
      "variant_id": "100041",
      "product_type_id": "1",
      "price_per_item_cents": 7900,
      "quantity": 1,
      "currency": 840,
      "results_status": "results.awaiting_sample"
    }
  ],
  "order_status": "order.payment_processing"
}

400

{
  "type": "https://api.terra-diagnostics.com/errors/validation-error",
  "title": "Validation Failed",
  "status": 400,
  "detail": "One or more required fields are missing or invalid",
  "instance": "/api/v1/orders",
  "invalid_fields": [
    {
      "field": "PhoneNumber",
      "message": "PhoneNumber is not a valid phone number for the provided country code",
      "tag": "phone_with_country",
      "value": "1234567890"
    }
  ]
}

IDs in order responses and webhooks (order_id, order_item_id, recipient_id, test_taker_id) are JSON strings - store them as strings. See Core concepts.

Ordering a variant that does not exist returns a 404 problem-detail response; ordering a product you have disabled in your catalog returns 403. See Errors.

5. Watch the fulfilment webhooks arrive

As the order progresses, order.status_changed webhooks land on your configured endpoint (in sandbox too). For example, once delivery details are available:

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

Webhook payloads use the same order.* status vocabulary as REST reads of the order - see Core concepts. In sandbox, payloads additionally carry supplier_item_id, which you need for simulating kit activation.

Verify the signature on every webhook you receive - see Webhooks.

6. Next: get results

In production you would now wait for the physical kit to reach your user. In sandbox, continue to Working with Sandbox to simulate the rest of the journey - kit activation, lab processing, and results - and to fetch and acknowledge the result.