> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/vantage-api-reference/core-resources/models.md).

# Models

## The ListOrdersResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ListOrdersResponse":{"type":"object","required":["orders"],"properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"next_cursor":{"type":"string","description":"Pass as ?cursor= for the next page; absent on the last page."}}},"OrderSummary":{"type":"object","required":["order_id","created_at","collection_type","order_status","total_cents","currency","items"],"properties":{"order_id":{"type":"string"},"client_order_reference_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"collection_type":{"type":"string","enum":["AT_HOME","GO_TO_LAB"]},"order_status":{"type":"string"},"total_cents":{"type":"integer"},"currency":{"type":"integer","description":"ISO-4217 numeric"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryItem"}}}},"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","item_status","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"type":"integer"},"results_status":{"type":"string"},"test_taker_id":{"type":"string"}}}}}}
```

## The OrderSummary object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderSummary":{"type":"object","required":["order_id","created_at","collection_type","order_status","total_cents","currency","items"],"properties":{"order_id":{"type":"string"},"client_order_reference_id":{"type":"string"},"created_at":{"type":"string","format":"date-time"},"collection_type":{"type":"string","enum":["AT_HOME","GO_TO_LAB"]},"order_status":{"type":"string"},"total_cents":{"type":"integer"},"currency":{"type":"integer","description":"ISO-4217 numeric"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryItem"}}}},"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","item_status","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"type":"integer"},"results_status":{"type":"string"},"test_taker_id":{"type":"string"}}}}}}
```

## The OrderSummaryItem object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","item_status","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"type":"integer"},"results_status":{"type":"string"},"test_taker_id":{"type":"string"}}}}}}
```

## The ListResultsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ListResultsResponse":{"type":"object","required":["results"],"properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/ResultSummary"}},"next_cursor":{"type":"string","description":"Pass as ?cursor= for the next page; absent on the last page."}}},"ResultSummary":{"type":"object","required":["order_item_id","order_id","variant_id","results_status","is_acknowledged","updated_at"],"properties":{"order_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"results_status":{"type":"string"},"is_acknowledged":{"type":"boolean"},"test_taker_id":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```

## The ResultSummary object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ResultSummary":{"type":"object","required":["order_item_id","order_id","variant_id","results_status","is_acknowledged","updated_at"],"properties":{"order_item_id":{"type":"string"},"order_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"results_status":{"type":"string"},"is_acknowledged":{"type":"boolean"},"test_taker_id":{"type":"string"},"updated_at":{"type":"string","format":"date-time"}}}}}}
```

## The ClientResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ClientResponse":{"type":"object","properties":{"client_id":{"type":"string"},"customer_id":{"type":"string"},"webhook_url":{"type":"string"}}}}}}
```

## The SimulateOrderRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"SimulateOrderRequest":{"type":"object","required":["event"],"properties":{"event":{"type":"string","description":"Lifecycle event to apply.","enum":["payment_complete","payment_failed","processing","delayed","cancelled","delivery_fulfilled","completed","kit_activated","sample_processing_in_lab","sample_rejected","partial_results_ready","results_ready","lab_processing_error","escalation_raised"]},"order_item_id":{"type":"string","description":"Narrow a results event to one order item."}}}}}}
```

## The SimulateOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"SimulateOrderResponse":{"type":"object","required":["order_id","applied_event"],"properties":{"order_id":{"type":"string"},"applied_event":{"type":"string"}}}}}}
```

## The UpdateCatalogSelectionRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"UpdateCatalogSelectionRequest":{"type":"object","required":["product_ids"],"properties":{"product_ids":{"type":"array","description":"Products to enable; everything else is disabled.","items":{"type":"string"}}}}}}}
```

## The UpdateCatalogSelectionResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"UpdateCatalogSelectionResponse":{"type":"object","required":["enabled_count"],"properties":{"enabled_count":{"type":"integer"}}}}}}
```

## The UpdateWebhookUrlRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"UpdateWebhookUrlRequest":{"type":"object","properties":{"webhook_url":{"type":"string"}}}}}}
```

## The AddressDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]}}}}
```

## The RecipientDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"RecipientDTO":{"description":"The recipient who will receive the test kit and may or may not be the test-taker (supplier-dependent)","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Full E.164 phone number as stored and dialed, including the \"+\" and country calling code (e.g. \"+447911123456\"). Leading zeros significant to the national number are preserved."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]}}}}
```

## The RecipientRequestDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"RecipientRequestDTO":{"description":"Recipient on an order-creation request. phone_number is a single E.164 string; the separate country_code field was removed and is silently ignored if still sent.","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Required, in E.164 format: a leading \"+\", the country calling code, then the national number (e.g. \"+447911123456\"). A bare national number or a separate country_code is rejected."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]}}}}
```

## The ProblemDetail object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ProblemDetail":{"description":"Standard error response format following RFC 7807 specification","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}}}}}}
```

## The SimulateTransitionProblem object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"SimulateTransitionProblem":{"description":"422 returned by the simulate endpoint when the requested event is not a valid forward transition from the current status. The RFC 7807 problem fields plus the two fields a client needs to recover without a GET round-trip. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects, and sealed allOf branches reject each other's properties.)","type":"object","required":["current_status","valid_events"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"current_status":{"type":"string","description":"The status the rejected event was evaluated against."},"valid_events":{"type":"array","description":"Events accepted from current_status, sorted.","items":{"type":"string"}}}}}}}
```

## The PaymentRequiredProblem object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"PaymentRequiredProblem":{"description":"402 returned by POST /orders when payment authorization fails. Nothing is created — no supplier order and no charge. The RFC 7807 problem fields plus a category the client can branch on. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects, and sealed allOf branches reject each other's properties.)","type":"object","required":["category","detail","status","title","type"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"category":{"type":"string","description":"Failure class for programmatic branching."}}}}}}
```

## The AuthenticationError object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"AuthenticationError":{"description":"Authentication error response (401)","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"}},"required":["detail","status","title","type"]}}}}
```

## The ActivateKitResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ActivateKitResponse":{"description":"Confirmation that kit was activated successfully","type":"object","properties":{"kit_id":{"type":"string"},"message":{"type":"string"},"success":{"type":"boolean"}}}}}}
```

## The ActivationContextAddress object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ActivationContextAddress":{"description":"Current address of the test-taker (may differ from shipping address)","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]}}}}
```

## The ActivationContextRecipient object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ActivationContextRecipient":{"description":"Test-taker personal information (may differ from original recipient). The former country_code field was removed and is silently ignored if still sent.","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"gender_at_birth":{"type":"string","enum":["male","female"]},"last_name":{"type":"string"},"phone_number":{"type":"string","description":"Required, in E.164 format: a leading \"+\", the country calling code, then the national number (e.g. \"+447911123456\"). A bare national number or a separate country_code is rejected."}},"required":["date_of_birth","email","gender_at_birth","phone_number"]}}}}
```

## The ActivationContextDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ActivationContextDTO":{"description":"Information provided by test-taker when activating their kit","type":"object","properties":{"address":{"$ref":"#/components/schemas/ActivationContextAddress"},"collection_date":{"type":"string"},"recipient":{"$ref":"#/components/schemas/ActivationContextRecipient"},"supplier_kit_id":{"type":"string"}},"required":["address"]},"ActivationContextAddress":{"description":"Current address of the test-taker (may differ from shipping address)","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"ActivationContextRecipient":{"description":"Test-taker personal information (may differ from original recipient). The former country_code field was removed and is silently ignored if still sent.","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string"},"first_name":{"type":"string"},"gender_at_birth":{"type":"string","enum":["male","female"]},"last_name":{"type":"string"},"phone_number":{"type":"string","description":"Required, in E.164 format: a leading \"+\", the country calling code, then the national number (e.g. \"+447911123456\"). A bare national number or a separate country_code is rejected."}},"required":["date_of_birth","email","gender_at_birth","phone_number"]}}}}
```

## The OrderItemRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderItemRequest":{"description":"Individual product variant and quantity in an order","type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":100},"variant_id":{"type":"string","minLength":1}},"required":["quantity","variant_id"]}}}}
```

## The CreateOrderRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"CreateOrderRequest":{"description":"Request body for creating a new diagnostic test order","type":"object","properties":{"client_order_reference_id":{"description":"Your unique order identifier that you generate, used for tracking and reconciliation. Not deduplicated server-side — retrying a create with the same value produces a second order.","type":"string","minLength":1,"maxLength":100},"collection_type":{"type":"string","enum":["AT_HOME","GO_TO_LAB"],"description":"Determines the required address field — shipping_address for AT_HOME, requested_lab_address for GO_TO_LAB."},"items":{"description":"Only need product_variant_id and quantity completely define what was ordered","type":"array","minItems":1,"items":{"$ref":"#/components/schemas/OrderItemRequest"}},"recipient":{"description":"Details of the person who ordered. Depending on the supplier recipient is not necessarily the test-taker. Although some suppliers enforce this constraint on us.","allOf":[{"$ref":"#/components/schemas/RecipientRequestDTO"}]},"requested_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"requested_lab":{"$ref":"#/components/schemas/RequestedLab"},"shipping_address":{"$ref":"#/components/schemas/AddressDTO"}},"required":["client_order_reference_id","collection_type","items","recipient"]},"OrderItemRequest":{"description":"Individual product variant and quantity in an order","type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":100},"variant_id":{"type":"string","minLength":1}},"required":["quantity","variant_id"]},"RecipientRequestDTO":{"description":"Recipient on an order-creation request. phone_number is a single E.164 string; the separate country_code field was removed and is silently ignored if still sent.","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Required, in E.164 format: a leading \"+\", the country calling code, then the national number (e.g. \"+447911123456\"). A bare national number or a separate country_code is rejected."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"RequestedLab":{"description":"GO_TO_LAB only: bind the order to a draw site chosen from GET /labs. code is the binding identity (row's code field); postal_code is a lookup hint (row's address.postal_code, ZIP+4 accepted - normalized to the 5-digit ZIP server-side; defaults to requested_lab_address.postal_code). Unknown codes are rejected with invalid_fields tag unknown_lab_code; if the lookup is temporarily unavailable the order is accepted unbound (confirmed_lab null).","type":"object","required":["code"],"properties":{"code":{"type":"string"},"postal_code":{"type":"string"}}}}}}
```

## The OrderFinancialDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderFinancialDTO":{"description":"Price breakdown including subtotal, tax, shipping, discounts","type":"object","properties":{"currency":{"description":"@Description ISO 4217 format (e.g. 840 = USD)","type":"integer"},"discount_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0}},"required":["currency","total_cents"]}}}}
```

## The OrderItemResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"type":"integer"},"item_status":{"type":"integer"},"lab_tracking_number":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"price_per_item_cents":{"type":"integer"},"product_type_id":{"type":"string"},"test_taker_ids":{"type":"array","description":"Test takers registered on this item (present once a kit is activated).","items":{"type":"string"}},"supplier_item_id":{"type":"string","description":"Supplier-side item identifier (kit ID once assigned). Recoverable here even if the webhook that carried it was missed."},"quantity":{"type":"integer"},"results_status":{"type":"string"},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity","currency"]}}}}
```

## The CreateOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"CreateOrderResponse":{"description":"Response containing the created order details including tracking information","type":"object","properties":{"confirmed_lab_address":{"allOf":[{"$ref":"#/components/schemas/AddressDTO"}],"description":"For GO_TO_LAB orders: the bound draw site's address - the end user's selection when requested_lab was sent and verified, otherwise the nearest site to the requested lab address. Best-effort - null when resolution is unavailable; the requisition is typically accepted at any of the supplier network's sites."},"confirmed_lab":{"anyOf":[{"$ref":"#/components/schemas/ConfirmedLab"},{"type":"null"}]},"estimated_delivery":{"type":"string"},"order_id":{"type":"string"},"order_items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemResponse"}},"order_status":{"type":"string","description":"Current fulfilment status in the REST `order.*` vocabulary. New orders start at `order.payment_processing`."},"recipient_id":{"type":"string"},"tracking_number":{"type":"string"}},"required":["order_id","recipient_id"]},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"ConfirmedLab":{"description":"The draw site this order is bound to - a GET /labs row minus its request-relative distance field. Null when no binding exists (no selection and nearest-site resolution unavailable, or selection accepted unbound during a lookup outage).","type":"object","required":["code","name","address"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean"}}},"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"type":"integer"},"item_status":{"type":"integer"},"lab_tracking_number":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"price_per_item_cents":{"type":"integer"},"product_type_id":{"type":"string"},"test_taker_ids":{"type":"array","description":"Test takers registered on this item (present once a kit is activated).","items":{"type":"string"}},"supplier_item_id":{"type":"string","description":"Supplier-side item identifier (kit ID once assigned). Recoverable here even if the webhook that carried it was missed."},"quantity":{"type":"integer"},"results_status":{"type":"string"},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity","currency"]}}}}
```

## The GetOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"GetOrderResponse":{"description":"Full order information including items, recipient, address, and financials","type":"object","properties":{"status_history":{"type":"array","description":"Lifecycle timeline, newest first (order fulfilment + item results events).","items":{"type":"object","required":["status","changed_at"],"properties":{"status":{"type":"string"},"order_item_id":{"type":"string"},"changed_at":{"type":"string","format":"date-time"},"escalation_level":{"type":"string","description":"Present only on escalation_raised entries."},"acknowledgment_due_by":{"type":"string","format":"date-time","description":"Present only on escalation_raised entries."}}}},"client_id":{"type":"string"},"client_order_reference_id":{"type":"string"},"collection_type":{"type":"string"},"confirmed_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderItemResponse"}},"order_financials":{"$ref":"#/components/schemas/OrderFinancialDTO"},"order_id":{"type":"string"},"order_status":{"type":"string","description":"Current fulfilment status in the REST `order.*` vocabulary."},"recipient":{"$ref":"#/components/schemas/RecipientDTO"},"requested_lab_address":{"$ref":"#/components/schemas/AddressDTO"},"confirmed_lab":{"anyOf":[{"$ref":"#/components/schemas/ConfirmedLab"},{"type":"null"}]},"requested_lab":{"allOf":[{"$ref":"#/components/schemas/RequestedLab"}],"description":"Echo of the selection sent at create time - lets a retrieval-only consumer tell \"selected but unbound\" from \"no selection made\"."},"shipping_address":{"$ref":"#/components/schemas/AddressDTO"}},"required":["order_id","client_id","client_order_reference_id","recipient","shipping_address","items","order_financials","collection_type"]},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]},"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"type":"integer"},"item_status":{"type":"integer"},"lab_tracking_number":{"type":"string"},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"price_per_item_cents":{"type":"integer"},"product_type_id":{"type":"string"},"test_taker_ids":{"type":"array","description":"Test takers registered on this item (present once a kit is activated).","items":{"type":"string"}},"supplier_item_id":{"type":"string","description":"Supplier-side item identifier (kit ID once assigned). Recoverable here even if the webhook that carried it was missed."},"quantity":{"type":"integer"},"results_status":{"type":"string"},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity","currency"]},"OrderFinancialDTO":{"description":"Price breakdown including subtotal, tax, shipping, discounts","type":"object","properties":{"currency":{"description":"@Description ISO 4217 format (e.g. 840 = USD)","type":"integer"},"discount_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0}},"required":["currency","total_cents"]},"RecipientDTO":{"description":"The recipient who will receive the test kit and may or may not be the test-taker (supplier-dependent)","type":"object","properties":{"date_of_birth":{"type":"string"},"email":{"type":"string","maxLength":100},"first_name":{"type":"string","maxLength":50},"gender_at_birth":{"type":"string","enum":["male","female"]},"id":{"type":"string"},"last_name":{"type":"string","maxLength":50},"phone_number":{"type":"string","description":"Full E.164 phone number as stored and dialed, including the \"+\" and country calling code (e.g. \"+447911123456\"). Leading zeros significant to the national number are preserved."}},"required":["date_of_birth","email","first_name","gender_at_birth","last_name","phone_number"]},"ConfirmedLab":{"description":"The draw site this order is bound to - a GET /labs row minus its request-relative distance field. Null when no binding exists (no selection and nearest-site resolution unavailable, or selection accepted unbound during a lookup outage).","type":"object","required":["code","name","address"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean"}}},"RequestedLab":{"description":"GO_TO_LAB only: bind the order to a draw site chosen from GET /labs. code is the binding identity (row's code field); postal_code is a lookup hint (row's address.postal_code, ZIP+4 accepted - normalized to the 5-digit ZIP server-side; defaults to requested_lab_address.postal_code). Unknown codes are rejected with invalid_fields tag unknown_lab_code; if the lookup is temporarily unavailable the order is accepted unbound (confirmed_lab null).","type":"object","required":["code"],"properties":{"code":{"type":"string"},"postal_code":{"type":"string"}}}}}}
```

## The RequestedLab object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"RequestedLab":{"description":"GO_TO_LAB only: bind the order to a draw site chosen from GET /labs. code is the binding identity (row's code field); postal_code is a lookup hint (row's address.postal_code, ZIP+4 accepted - normalized to the 5-digit ZIP server-side; defaults to requested_lab_address.postal_code). Unknown codes are rejected with invalid_fields tag unknown_lab_code; if the lookup is temporarily unavailable the order is accepted unbound (confirmed_lab null).","type":"object","required":["code"],"properties":{"code":{"type":"string"},"postal_code":{"type":"string"}}}}}}
```

## The ConfirmedLab object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ConfirmedLab":{"description":"The draw site this order is bound to - a GET /labs row minus its request-relative distance field. Null when no binding exists (no selection and nearest-site resolution unavailable, or selection accepted unbound during a lookup outage).","type":"object","required":["code","name","address"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"}},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean"}}},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]}}}}
```

## The CreateOrderValidationError object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"CreateOrderValidationError":{"description":"Validation error when creating an order","type":"object","properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"invalid_fields":{"type":"array","description":"Per-field validation errors","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"},"tag":{"type":"string"},"value":{"type":"string"}}}},"supported_ship_to_countries":{"type":"array","description":"Present when the order was rejected for an unsupported country (tag unsupported_ship_to_country) - the ISO-3166 alpha-2 codes this test can be ordered in.","items":{"type":"string"}}},"required":["detail","instance","status","title","type"]}}}}
```

## The OrderStatusChangedEvent object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderStatusChangedEvent":{"type":"object","required":["event_type","event_id","timestamp","data"],"properties":{"event_type":{"type":"string","const":"order.status_changed"},"event_id":{"type":"string","description":"Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header."},"timestamp":{"type":"integer","description":"Unix seconds when the event was sent."},"data":{"type":"object","required":["order_id","status"],"properties":{"order_id":{"type":"string"},"status":{"type":"string","enum":["order.payment_processing","order.payment_complete","order.payment_failed","order.processing","order.delayed","order.cancelled","order.completed","order.delivery_fulfilled"]},"tracking_number":{"type":"string","description":"Present once delivery details are available."},"supplier_item_id":{"type":"string","description":"Sandbox payloads only — the supplier-side kit ID."}}}}}}}}
```

## The OrderItemResultsStatusChangedEvent object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OrderItemResultsStatusChangedEvent":{"type":"object","required":["event_type","event_id","timestamp","data"],"properties":{"event_type":{"type":"string","const":"order_item.results_status_change"},"event_id":{"type":"string","description":"Unique per event (64-bit id serialized as a string) — deduplicate on this. Equals the X-Terra-Trace-Id header."},"timestamp":{"type":"integer","description":"Unix seconds when the event was sent."},"data":{"type":"object","required":["order_id","order_item_id","variant_id","results_status","test_taker"],"properties":{"order_id":{"type":"string"},"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"results_status":{"type":"string","enum":["results.kit_activated","results.sample_processing_in_lab","results.sample_rejected","results.partial_results_ready","results.results_ready","results.lab_processing_error","results.escalation_raised"]},"test_taker":{"type":"object","required":["test_taker_id","first_name","last_name","email","phone_number"],"properties":{"test_taker_id":{"type":"string"},"first_name":{"type":"string"},"last_name":{"type":"string"},"email":{"type":"string"},"phone_number":{"type":"string","description":"E.164 phone number"}}},"escalation_level":{"type":"string","description":"Present on escalation_raised.","enum":["not_escalated","very_low","low","medium","high","very_high"]},"acknowledgment_due_by":{"type":"string","description":"Present on escalation_raised — ISO 8601 deadline."},"failure_cause":{"type":"string","description":"Present on sample_rejected."}}}}}}}}
```

## The GetResultsURLResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"GetResultsURLResponse":{"description":"Response containing a presigned URL to download test results","type":"object","properties":{"download_url":{"type":"string"},"expires_at":{"type":"string"},"format":{"type":"string","enum":["json"]}}}}}}
```

## The AcknowledgeResultsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"AcknowledgeResultsResponse":{"description":"Confirmation that results were acknowledged","type":"object","properties":{"status":{"type":"string"}}}}}}
```

## The AvailabilityStatus object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"AvailabilityStatus":{"type":"integer","format":"int32","enum":[0,1,2]}}}}
```

## The Currency object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"Currency":{"type":"integer","format":"int32","enum":[0,840,978,826]}}}}
```

## The Image object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}}}}}
```

## The ProductVariant object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ProductVariant":{"type":"object","properties":{"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_name":{"type":"string"}}},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}}}}}
```

## The Product object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"Product":{"type":"object","properties":{"enabled":{"type":"boolean","description":"Present only on ?show_all=true — the caller's per-product curation flag."},"availability":{"$ref":"#/components/schemas/AvailabilityStatus"},"base_price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"model_descriptive_attrs":{"type":"object","additionalProperties":{"type":"string"}},"name":{"type":"string"},"product_type_id":{"type":"integer","format":"int64"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"AvailabilityStatus":{"type":"integer","format":"int32","enum":[0,1,2]},"Currency":{"type":"integer","format":"int32","enum":[0,840,978,826]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"integer","format":"int64"},"product_id":{"type":"integer","format":"int64"},"url":{"type":"string"},"variant_id":{"type":"integer","format":"int64"},"width":{"type":"integer","format":"int32"}}},"ProductVariant":{"type":"object","properties":{"available_collection_types":{"type":"array","items":{"type":"string"}},"supported_ship_to_countries":{"type":"array","description":"ISO-3166 alpha-2 codes this test can be ordered in (AT_HOME shipping destination; for GO_TO_LAB, the requested lab country). Gate your address form on it - orders outside these countries are rejected with an unsupported_ship_to_country field error.","items":{"type":"string"}},"currency":{"type":"integer","format":"int32"},"descriptive_attrs_override":{"type":"object","additionalProperties":{}},"id":{"type":"integer","format":"int64"},"images":{"type":"array","items":{"$ref":"#/components/schemas/Image"}},"price_cents":{"type":"integer","format":"int32"},"product_id":{"type":"integer","format":"int64"},"product_type_id":{"type":"integer","format":"int64"},"variant_availability":{"type":"integer","format":"int32"},"variant_defining_attrs":{"type":"object","additionalProperties":{}},"variant_name":{"type":"string"}}}}}}
```

## The ProductType object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ProductType":{"type":"object","properties":{"description":{"type":"string"},"id":{"type":"integer","format":"int64"},"name":{"type":"string"}}}}}}
```

## The ListLabsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"ListLabsResponse":{"type":"object","required":["labs"],"properties":{"labs":{"type":"array","items":{"$ref":"#/components/schemas/PSCLocation"}}}},"PSCLocation":{"description":"A Patient Service Center (lab draw site).","type":"object","required":["code","name","address","phone","latitude","longitude","scheduling","distance"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"},"description":"Opening hours keyed by weekday."},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean","description":"Whether online scheduling is open."},"distance":{"type":"number","description":"Miles from the requested zip."}}},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]}}}}
```

## The PSCLocation object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"PSCLocation":{"description":"A Patient Service Center (lab draw site).","type":"object","required":["code","name","address","phone","latitude","longitude","scheduling","distance"],"properties":{"code":{"type":"string"},"name":{"type":"string"},"address":{"$ref":"#/components/schemas/AddressDTO"},"phone":{"type":"string"},"hours":{"type":"object","additionalProperties":{"type":"string"},"description":"Opening hours keyed by weekday."},"latitude":{"type":"number"},"longitude":{"type":"number"},"scheduling":{"type":"boolean","description":"Whether online scheduling is open."},"distance":{"type":"number","description":"Miles from the requested zip."}}},"AddressDTO":{"description":"Physical address for shipping test kits","type":"object","properties":{"address_line_1":{"type":"string","minLength":1,"maxLength":100},"address_line_2":{"type":"string","maxLength":100},"administrative_area":{"type":"string","maxLength":50},"city":{"type":"string","minLength":1,"maxLength":50},"country_code":{"type":"string","description":"ISO 3166-1 alpha-2 (e.g., \"GB\", \"US\")"},"id":{"type":"integer"},"is_validated":{"type":"boolean"},"postal_code":{"type":"string"}},"required":["address_line_1","administrative_area","city","country_code","postal_code"]}}}}
```

## The OverviewResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"OverviewResponse":{"type":"object","required":["orders","results","webhooks"],"properties":{"orders":{"type":"object","required":["total","by_status"],"properties":{"total":{"type":"integer"},"by_status":{"type":"object","additionalProperties":{"type":"integer"},"description":"Order counts keyed by current fulfilment status string."}}},"results":{"type":"object","required":["total","missing"],"properties":{"total":{"type":"integer"},"missing":{"type":"integer"}}},"webhooks":{"type":"object","required":["failed_total","daily"],"properties":{"failed_total":{"type":"integer"},"daily":{"type":"array","items":{"type":"object","required":["date","failed"],"properties":{"date":{"type":"string"},"failed":{"type":"integer"}}}}}}}}}}}
```

## The WebhookDeliveriesResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"WebhookDeliveriesResponse":{"type":"object","required":["deliveries"],"properties":{"deliveries":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"next_cursor":{"type":"string","description":"Pass as ?cursor= for the next page; absent on the last page."}}},"WebhookDelivery":{"type":"object","required":["event_id","event_type","order_id","order_item_id","outcome","final_status_code","attempts","completed_at","event_created_at"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string","description":"Same vocabulary as the webhook event_type field (currently order.status_changed, order_item.status_changed and order_item.results_status_change). Open set - new event types may appear; treat unknown values as deliveries of a newer event family."},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"outcome":{"type":"string","description":"One of: delivered, rejected, invalid, dead_lettered, replayed."},"final_status_code":{"type":["integer","null"]},"attempts":{"type":"integer"},"completed_at":{"type":"string","format":"date-time"},"event_created_at":{"type":"string","format":"date-time"}}}}}}
```

## The WebhookDelivery object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.07.23.2"},"components":{"schemas":{"WebhookDelivery":{"type":"object","required":["event_id","event_type","order_id","order_item_id","outcome","final_status_code","attempts","completed_at","event_created_at"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string","description":"Same vocabulary as the webhook event_type field (currently order.status_changed, order_item.status_changed and order_item.results_status_change). Open set - new event types may appear; treat unknown values as deliveries of a newer event family."},"order_id":{"type":"string"},"order_item_id":{"type":"string"},"outcome":{"type":"string","description":"One of: delivered, rejected, invalid, dead_lettered, replayed."},"final_status_code":{"type":["integer","null"]},"attempts":{"type":"integer"},"completed_at":{"type":"string","format":"date-time"},"event_created_at":{"type":"string","format":"date-time"}}}}}}
```