Test Collection Methods

AT_HOME vs GO_TO_LAB orders: which address fields each requires, how lab routing works, and how to find nearby lab draw sites.

Overview

Depending on the supplier and the product, a test can support multiple collection methods - ways for the end user to provide the sample. A variant advertises what it supports in available_collection_types; every order picks one via collection_type.

collection_type	Meaning
AT_HOME	Kits are sent to the end user's home. They follow the kit instructions to self-collect.
GO_TO_LAB	The end user visits a lab draw site (Patient Service Center), where a professional collects the sample.

The collection type determines which address field the order requires:

• AT_HOME → shipping_address (where to ship the kit)

• GO_TO_LAB → requested_lab_address (used to route the order to the closest available lab)

Where a test can be ordered

Every variant advertises the countries it can be ordered in as supported_ship_to_countries (ISO-3166 alpha-2 codes) — for AT_HOME this is the kit's shipping destination; for GO_TO_LAB, the country of the requested lab:

{
  "id": 100011,
  "variant_name": "Standard Kit",
  "available_collection_types": ["AT_HOME"],
  "supported_ship_to_countries": ["GB"]
}

Gate your address form (or country picker) on this list. Orders outside it are rejected with a 400 you can map straight onto the form — the invalid_fields entry carries the tag unsupported_ship_to_country and the field that failed (shipping_address.country_code or requested_lab_address.country_code), and the problem detail includes the allowed codes:

{
  "detail": "This test isn't available in the provided country. Supported country codes: GB.",
  "status": 400,
  "invalid_fields": [
    {
      "field": "shipping_address.country_code",
      "message": "must be one of: GB",
      "tag": "unsupported_ship_to_country",
      "value": "US"
    }
  ],
  "supported_ship_to_countries": ["GB"]
}

AT_HOME orders

Request

{
  "client_order_reference_id": "TEST-ORDER-001",
  "collection_type": "AT_HOME",
  "recipient": {
    "first_name": "John",
    "last_name": "Tan",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "date_of_birth": "1995-10-10",
    "gender_at_birth": "male"
  },
  "shipping_address": {
    "address_line_1": "123 High Street",
    "city": "London",
    "administrative_area": "England",
    "country_code": "GB",
    "postal_code": "SW1A 1AA"
  },
  "items": [
    {
      "variant_id": "100011",
      "quantity": 1
    }
  ]
}

Response (201)

{
  "order_id": "256488482397134848",
  "recipient_id": "256488482397134849",
  "order_items": [
    {
      "order_id": "256488482397134848",
      "order_item_id": "256488482397134851",
      "variant_id": "100011",
      "product_type_id": "1",
      "price_per_item_cents": 3999,
      "quantity": 1,
      "currency": 826,
      "results_status": "results.awaiting_sample"
    }
  ],
  "order_status": "order.payment_processing"
}

GO_TO_LAB orders

For GO_TO_LAB, send the address the end user would like to be near as requested_lab_address. Terra uses it as a proxy to route the order to the closest available lab. To let the user pick a specific draw site up front, list nearby locations first (see Finding nearby lab draw sites):

Request

{
  "client_order_reference_id": "TEST-ORDER-002",
  "collection_type": "GO_TO_LAB",
  "recipient": {
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone_number": "[phone]",
    "date_of_birth": "1990-05-15",
    "gender_at_birth": "female"
  },
  "requested_lab_address": {
    "address_line_1": "350 5th Avenue",
    "city": "New York",
    "administrative_area": "NY",
    "country_code": "US",
    "postal_code": "10118"
  },
  "items": [
    {
      "variant_id": "100011",
      "quantity": 1
    }
  ]
}

Response (201)

{
  "order_id": "256488482397134852",
  "recipient_id": "256488482397134853",
  "order_items": [
    {
      "order_id": "256488482397134852",
      "order_item_id": "256488482397134855",
      "variant_id": "100011",
      "product_type_id": "1",
      "price_per_item_cents": 3999,
      "quantity": 1,
      "currency": 840,
      "results_status": "results.awaiting_sample"
    }
  ],
  "order_status": "order.payment_processing"
}

Order responses include a confirmed_lab_address field: the nearest draw site to the requested lab address, resolved at order time. It is best-effort - null when resolution is unavailable, so don't build a flow that requires it. The requisition is typically accepted at any of the network's sites (see the labs listing below).

Finding nearby lab draw sites

To let your end user choose a convenient location before placing a GO_TO_LAB order, list nearby Patient Service Centers for a US zip code:

curl 'https://vantage-sandbox.tryterra.co/api/v1/labs?zip_code=10001' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

{
  "labs": [
    {
      "code": "PSC12345",
      "name": "Quest Diagnostics - Midtown",
      "address": {
        "address_line_1": "245 W 35th St",
        "city": "New York",
        "administrative_area": "NY",
        "country_code": "US",
        "postal_code": "10001"
      },
      "phone": "[phone]",
      "hours": { "monday": "08:00-17:00" },
      "latitude": 40.7549,
      "longitude": -73.984,
      "scheduling": true,
      "distance": 0.4
    }
  ]
}

distance is in miles from the requested zip code; scheduling indicates whether online scheduling is open at that site.

Letting the user pick a draw site

To bind a GO_TO_LAB order to the site your user chose (instead of the automatic nearest-site resolution), pass the chosen row's code and address.postal_code as requested_lab when creating the order:

{
  "collection_type": "GO_TO_LAB",
  "requested_lab_address": { "...": "the user's search area" },
  "requested_lab": { "code": "PSC12345", "postal_code": "10001-6975" }
}

Both values come verbatim from the GET /labs row (ZIP+4 is fine - it is normalized server-side). The outcomes:

• Bound - the order response (and any later GET /orders/{id}) carries confirmed_lab (the full site: code, name, address, phone, hours) and confirmed_lab_address. Render it as "your draw site".

• Unknown code - 400 with an invalid_fields entry on requested_lab.code tagged unknown_lab_code. The site list may have changed: re-fetch GET /labs and let the user re-select. Nothing was created, so retrying is safe.

• Lookup temporarily unavailable - the order is accepted unbound (confirmed_lab is null). The requisition is typically valid at any of the network's sites, so a brief outage never fails an order. GET /orders/{id} echoes your requested_lab so you can tell this case apart from "no selection was made".

Without requested_lab, Terra falls back to resolving the nearest site to requested_lab_address (best-effort).