> 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/reference/vantage-api/models.md).

# Models

## The ListOrdersResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ListOrdersResponse":{"type":"object","description":"One page of orders, newest first. Versions before 2026-10-15 serve the items under `orders` instead of `data`, no `has_more`, and omit `next_cursor` on the last page.","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummary"}},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null on the last page."}}},"OrderSummary":{"type":"object","required":["order_id","created_at","collection_type","order_status","total_cents","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":{"$ref":"#/components/schemas/Currency"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryItem"}}}},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"test_taker_id":{"type":"string"}}},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]}}}}
```

## The OrderSummary object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"OrderSummary":{"type":"object","required":["order_id","created_at","collection_type","order_status","total_cents","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":{"$ref":"#/components/schemas/Currency"},"items":{"type":"array","items":{"$ref":"#/components/schemas/OrderSummaryItem"}}}},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"test_taker_id":{"type":"string"}}},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]}}}}
```

## The OrderSummaryItem object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"OrderSummaryItem":{"type":"object","required":["order_item_id","variant_id","results_status"],"properties":{"order_item_id":{"type":"string"},"variant_id":{"type":"string"},"product_name":{"type":"string"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"test_taker_id":{"type":"string"}}},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]}}}}
```

## The ListResultsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ListResultsResponse":{"type":"object","description":"One page of order items with result activity, newest first. Versions before 2026-10-15 serve the items under `results` instead of `data`, no `has_more`, and omit `next_cursor` on the last page.","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResultSummary"}},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null 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.10.22"},"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.10.22"},"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.10.22"},"components":{"schemas":{"SimulateOrderRequest":{"type":"object","required":["event"],"properties":{"event":{"type":"string","description":"Lifecycle event to apply. `genome_processing`, `sample_reanalysis` and `reanalysed` apply to DNA order items only; `reanalysed` stores the next version of the item's result before its webhook fires.","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","genome_processing","sample_reanalysis","reanalysed"]},"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.10.22"},"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.10.22"},"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.10.22"},"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.10.22"},"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.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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.10.22"},"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.10.22"},"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.10.22"},"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.10.22"},"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."},"code":{"type":"string","description":"Why authorization failed. `payment_method_missing`: the account has no payment method on file; add one and retry. `card_declined`: the card issuer refused the charge; update or replace the card first. `payment_authorization_failed`: anything else, such as a temporary payment provider error; retrying may succeed. New values may be added, so treat an unknown code like `payment_authorization_failed`.","enum":["payment_method_missing","card_declined","payment_authorization_failed"]}}}}}}
```

## The AuthenticationError object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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.10.22"},"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.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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","integer"],"minLength":1,"description":"The variant's id as a decimal string. A JSON number is also accepted."}},"required":["quantity","variant_id"]}}}}
```

## The CreateOrderRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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. A GO_TO_LAB variant whose collection_visit is `clinic` also needs shipping_address, where its kit is posted; any other GO_TO_LAB order must not send one."},"dna":{"$ref":"#/components/schemas/DNADetails"},"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"]},"DNADetails":{"description":"What the DNA test needs to know about its end user, so the end user never deals with the supplier. Which details an order must carry depends on the variant ordered: each DNA variant lists them, by the JSON paths used here, in required_dna_details. A DNA order missing one, or with an invalid field, is rejected with 400 before payment, and invalid_fields names each field by its JSON path (for example dna.health_measurements.height_cm) with tag required, type, range, pair, enum, unexpected, words, item, rfc3339, future, max, iso_date or recipient_mismatch. Details the variant does not require may still be sent and are validated the same way. A person who answers true to an eligibility question is rejected with 400 and tag ineligible. Sex at birth is taken from recipient.gender_at_birth. Errors never echo the submitted values. Ignored when no item is a DNA product (product_type_id 2). Stored per DNA order item and never returned by the API.","type":"object","properties":{"health_measurements":{"$ref":"#/components/schemas/DNAHealthMeasurements"},"ancestry":{"$ref":"#/components/schemas/DNAAncestry"},"lifestyle":{"$ref":"#/components/schemas/DNALifestyle"},"medical_history":{"$ref":"#/components/schemas/DNAMedicalHistory"},"eligibility":{"$ref":"#/components/schemas/DNAEligibility"},"consent":{"$ref":"#/components/schemas/DNAConsent"}}},"DNAHealthMeasurements":{"description":"The end user's most recent measurements, in the units named by each key. Send a key when the variant's required_dna_details lists it; for a lab measurement, send null when the end user does not know the value (height and weight cannot be null). Ranges are the narrowest any DNA supplier accepts.","type":"object","properties":{"height_cm":{"description":"Height in centimetres (5 ft 6 in is 167.64).","type":"number","minimum":31,"maximum":272},"weight_kg":{"description":"Weight in kilograms.","type":"number","minimum":20,"maximum":600},"total_cholesterol_mg_dl":{"description":"Total cholesterol from the last blood test, mg/dL.","type":["number","null"],"exclusiveMinimum":0,"maximum":1000},"systolic_blood_pressure_mmhg":{"description":"Systolic blood pressure, mmHg. Null or left out exactly when diastolic is.","type":["integer","null"],"minimum":1,"maximum":999},"diastolic_blood_pressure_mmhg":{"description":"Diastolic blood pressure, mmHg. Null or left out exactly when systolic is.","type":["integer","null"],"minimum":1,"maximum":999},"fasting_glucose_mg_dl":{"description":"Fasting blood glucose, mg/dL.","type":["number","null"],"minimum":20,"maximum":500},"hba1c_percent":{"description":"HbA1c (A1C), percent.","type":["number","null"],"exclusiveMinimum":0,"maximum":50}}},"DNAAncestry":{"type":"object","required":["groups","ethnicity"],"properties":{"groups":{"description":"Every ancestry that applies. Duplicates are ignored.","type":"array","minItems":1,"items":{"type":"string","enum":["african_american","afro_caribbean","sub_saharan_african","african","alaska_native","central_asian","east_asian","hispanic","jewish_ashkenazi","jewish_sephardic_mizrahi_other","latino","middle_eastern_west_asian_north_african","native_american_indigenous_canadian","pacific_islander_oceanian","south_asian","southeast_asian","white_european","other"]}},"other":{"description":"Required when groups includes other, rejected otherwise. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","maxLength":100},"ethnicity":{"description":"Regional origin or ethnic roots, for example Persian. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","minLength":1,"maxLength":100}}},"DNALifestyle":{"type":"object","required":["smoking","alcohol"],"properties":{"smoking":{"$ref":"#/components/schemas/DNASmoking"},"alcohol":{"type":"string","enum":["never","couple_per_month","one_to_seven_per_week","eight_to_fourteen_per_week","more_than_fourteen_per_week"],"description":"How often the end user drinks alcohol (a couple of drinks per month, 1-7, 8-14 or more than 14 drinks per week)."}}},"DNASmoking":{"description":"years_since_quit is required for former and cigarettes_per_day for trying_to_quit and current; each is rejected for any other status.","type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["never","former","trying_to_quit","current"]},"years_since_quit":{"type":"integer","minimum":1,"maximum":100},"cigarettes_per_day":{"type":"integer","minimum":1,"maximum":100}}},"DNAMedicalHistory":{"type":"object","required":["diagnosed_conditions"],"properties":{"diagnosed_conditions":{"description":"Diseases or conditions the end user has or has had, in their own words; [] when none.","type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":200}}}},"DNAEligibility":{"description":"A DNA test cannot be run for a person who answers true to either question (donor DNA can be in the sample); such an order is rejected with tag ineligible.","type":"object","required":["bone_marrow_or_stem_cell_recipient","blood_transfusion_last_two_weeks"],"properties":{"bone_marrow_or_stem_cell_recipient":{"type":"boolean"},"blood_transfusion_last_two_weeks":{"type":"boolean"}}},"DNAConsent":{"description":"The end user's consent to the DNA test, collected in your app before ordering.","type":"object","required":["accepted_at","signature_name","date_of_birth","document_version"],"properties":{"accepted_at":{"description":"When the end user accepted, RFC 3339. Must not be later than the server time.","type":"string","format":"date-time"},"signature_name":{"description":"The full name the end user typed as their signature.","type":"string","minLength":1,"maxLength":200},"date_of_birth":{"description":"The date of birth the end user confirmed when signing. Must equal recipient.date_of_birth.","type":"string","format":"date"},"document_version":{"description":"The version of the consent document the end user was shown.","type":"string","minLength":1,"maxLength":100}}},"OrderItemRequest":{"description":"Individual product variant and quantity in an order","type":"object","properties":{"quantity":{"type":"integer","minimum":1,"maximum":100},"variant_id":{"type":["string","integer"],"minLength":1,"description":"The variant's id as a decimal string. A JSON number is also accepted."}},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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 DNADetails object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNADetails":{"description":"What the DNA test needs to know about its end user, so the end user never deals with the supplier. Which details an order must carry depends on the variant ordered: each DNA variant lists them, by the JSON paths used here, in required_dna_details. A DNA order missing one, or with an invalid field, is rejected with 400 before payment, and invalid_fields names each field by its JSON path (for example dna.health_measurements.height_cm) with tag required, type, range, pair, enum, unexpected, words, item, rfc3339, future, max, iso_date or recipient_mismatch. Details the variant does not require may still be sent and are validated the same way. A person who answers true to an eligibility question is rejected with 400 and tag ineligible. Sex at birth is taken from recipient.gender_at_birth. Errors never echo the submitted values. Ignored when no item is a DNA product (product_type_id 2). Stored per DNA order item and never returned by the API.","type":"object","properties":{"health_measurements":{"$ref":"#/components/schemas/DNAHealthMeasurements"},"ancestry":{"$ref":"#/components/schemas/DNAAncestry"},"lifestyle":{"$ref":"#/components/schemas/DNALifestyle"},"medical_history":{"$ref":"#/components/schemas/DNAMedicalHistory"},"eligibility":{"$ref":"#/components/schemas/DNAEligibility"},"consent":{"$ref":"#/components/schemas/DNAConsent"}}},"DNAHealthMeasurements":{"description":"The end user's most recent measurements, in the units named by each key. Send a key when the variant's required_dna_details lists it; for a lab measurement, send null when the end user does not know the value (height and weight cannot be null). Ranges are the narrowest any DNA supplier accepts.","type":"object","properties":{"height_cm":{"description":"Height in centimetres (5 ft 6 in is 167.64).","type":"number","minimum":31,"maximum":272},"weight_kg":{"description":"Weight in kilograms.","type":"number","minimum":20,"maximum":600},"total_cholesterol_mg_dl":{"description":"Total cholesterol from the last blood test, mg/dL.","type":["number","null"],"exclusiveMinimum":0,"maximum":1000},"systolic_blood_pressure_mmhg":{"description":"Systolic blood pressure, mmHg. Null or left out exactly when diastolic is.","type":["integer","null"],"minimum":1,"maximum":999},"diastolic_blood_pressure_mmhg":{"description":"Diastolic blood pressure, mmHg. Null or left out exactly when systolic is.","type":["integer","null"],"minimum":1,"maximum":999},"fasting_glucose_mg_dl":{"description":"Fasting blood glucose, mg/dL.","type":["number","null"],"minimum":20,"maximum":500},"hba1c_percent":{"description":"HbA1c (A1C), percent.","type":["number","null"],"exclusiveMinimum":0,"maximum":50}}},"DNAAncestry":{"type":"object","required":["groups","ethnicity"],"properties":{"groups":{"description":"Every ancestry that applies. Duplicates are ignored.","type":"array","minItems":1,"items":{"type":"string","enum":["african_american","afro_caribbean","sub_saharan_african","african","alaska_native","central_asian","east_asian","hispanic","jewish_ashkenazi","jewish_sephardic_mizrahi_other","latino","middle_eastern_west_asian_north_african","native_american_indigenous_canadian","pacific_islander_oceanian","south_asian","southeast_asian","white_european","other"]}},"other":{"description":"Required when groups includes other, rejected otherwise. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","maxLength":100},"ethnicity":{"description":"Regional origin or ethnic roots, for example Persian. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","minLength":1,"maxLength":100}}},"DNALifestyle":{"type":"object","required":["smoking","alcohol"],"properties":{"smoking":{"$ref":"#/components/schemas/DNASmoking"},"alcohol":{"type":"string","enum":["never","couple_per_month","one_to_seven_per_week","eight_to_fourteen_per_week","more_than_fourteen_per_week"],"description":"How often the end user drinks alcohol (a couple of drinks per month, 1-7, 8-14 or more than 14 drinks per week)."}}},"DNASmoking":{"description":"years_since_quit is required for former and cigarettes_per_day for trying_to_quit and current; each is rejected for any other status.","type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["never","former","trying_to_quit","current"]},"years_since_quit":{"type":"integer","minimum":1,"maximum":100},"cigarettes_per_day":{"type":"integer","minimum":1,"maximum":100}}},"DNAMedicalHistory":{"type":"object","required":["diagnosed_conditions"],"properties":{"diagnosed_conditions":{"description":"Diseases or conditions the end user has or has had, in their own words; [] when none.","type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":200}}}},"DNAEligibility":{"description":"A DNA test cannot be run for a person who answers true to either question (donor DNA can be in the sample); such an order is rejected with tag ineligible.","type":"object","required":["bone_marrow_or_stem_cell_recipient","blood_transfusion_last_two_weeks"],"properties":{"bone_marrow_or_stem_cell_recipient":{"type":"boolean"},"blood_transfusion_last_two_weeks":{"type":"boolean"}}},"DNAConsent":{"description":"The end user's consent to the DNA test, collected in your app before ordering.","type":"object","required":["accepted_at","signature_name","date_of_birth","document_version"],"properties":{"accepted_at":{"description":"When the end user accepted, RFC 3339. Must not be later than the server time.","type":"string","format":"date-time"},"signature_name":{"description":"The full name the end user typed as their signature.","type":"string","minLength":1,"maxLength":200},"date_of_birth":{"description":"The date of birth the end user confirmed when signing. Must equal recipient.date_of_birth.","type":"string","format":"date"},"document_version":{"description":"The version of the consent document the end user was shown.","type":"string","minLength":1,"maxLength":100}}}}}}
```

## The DNAHealthMeasurements object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAHealthMeasurements":{"description":"The end user's most recent measurements, in the units named by each key. Send a key when the variant's required_dna_details lists it; for a lab measurement, send null when the end user does not know the value (height and weight cannot be null). Ranges are the narrowest any DNA supplier accepts.","type":"object","properties":{"height_cm":{"description":"Height in centimetres (5 ft 6 in is 167.64).","type":"number","minimum":31,"maximum":272},"weight_kg":{"description":"Weight in kilograms.","type":"number","minimum":20,"maximum":600},"total_cholesterol_mg_dl":{"description":"Total cholesterol from the last blood test, mg/dL.","type":["number","null"],"exclusiveMinimum":0,"maximum":1000},"systolic_blood_pressure_mmhg":{"description":"Systolic blood pressure, mmHg. Null or left out exactly when diastolic is.","type":["integer","null"],"minimum":1,"maximum":999},"diastolic_blood_pressure_mmhg":{"description":"Diastolic blood pressure, mmHg. Null or left out exactly when systolic is.","type":["integer","null"],"minimum":1,"maximum":999},"fasting_glucose_mg_dl":{"description":"Fasting blood glucose, mg/dL.","type":["number","null"],"minimum":20,"maximum":500},"hba1c_percent":{"description":"HbA1c (A1C), percent.","type":["number","null"],"exclusiveMinimum":0,"maximum":50}}}}}}
```

## The DNAAncestry object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAAncestry":{"type":"object","required":["groups","ethnicity"],"properties":{"groups":{"description":"Every ancestry that applies. Duplicates are ignored.","type":"array","minItems":1,"items":{"type":"string","enum":["african_american","afro_caribbean","sub_saharan_african","african","alaska_native","central_asian","east_asian","hispanic","jewish_ashkenazi","jewish_sephardic_mizrahi_other","latino","middle_eastern_west_asian_north_african","native_american_indigenous_canadian","pacific_islander_oceanian","south_asian","southeast_asian","white_european","other"]}},"other":{"description":"Required when groups includes other, rejected otherwise. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","maxLength":100},"ethnicity":{"description":"Regional origin or ethnic roots, for example Persian. Letters, spaces and ' ( ) * + , - . / \" only, at most 100 characters.","type":"string","minLength":1,"maxLength":100}}}}}}
```

## The DNALifestyle object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNALifestyle":{"type":"object","required":["smoking","alcohol"],"properties":{"smoking":{"$ref":"#/components/schemas/DNASmoking"},"alcohol":{"type":"string","enum":["never","couple_per_month","one_to_seven_per_week","eight_to_fourteen_per_week","more_than_fourteen_per_week"],"description":"How often the end user drinks alcohol (a couple of drinks per month, 1-7, 8-14 or more than 14 drinks per week)."}}},"DNASmoking":{"description":"years_since_quit is required for former and cigarettes_per_day for trying_to_quit and current; each is rejected for any other status.","type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["never","former","trying_to_quit","current"]},"years_since_quit":{"type":"integer","minimum":1,"maximum":100},"cigarettes_per_day":{"type":"integer","minimum":1,"maximum":100}}}}}}
```

## The DNASmoking object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNASmoking":{"description":"years_since_quit is required for former and cigarettes_per_day for trying_to_quit and current; each is rejected for any other status.","type":"object","required":["status"],"properties":{"status":{"type":"string","enum":["never","former","trying_to_quit","current"]},"years_since_quit":{"type":"integer","minimum":1,"maximum":100},"cigarettes_per_day":{"type":"integer","minimum":1,"maximum":100}}}}}}
```

## The DNAMedicalHistory object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAMedicalHistory":{"type":"object","required":["diagnosed_conditions"],"properties":{"diagnosed_conditions":{"description":"Diseases or conditions the end user has or has had, in their own words; [] when none.","type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":200}}}}}}}
```

## The DNAEligibility object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAEligibility":{"description":"A DNA test cannot be run for a person who answers true to either question (donor DNA can be in the sample); such an order is rejected with tag ineligible.","type":"object","required":["bone_marrow_or_stem_cell_recipient","blood_transfusion_last_two_weeks"],"properties":{"bone_marrow_or_stem_cell_recipient":{"type":"boolean"},"blood_transfusion_last_two_weeks":{"type":"boolean"}}}}}}
```

## The DNAConsent object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAConsent":{"description":"The end user's consent to the DNA test, collected in your app before ordering.","type":"object","required":["accepted_at","signature_name","date_of_birth","document_version"],"properties":{"accepted_at":{"description":"When the end user accepted, RFC 3339. Must not be later than the server time.","type":"string","format":"date-time"},"signature_name":{"description":"The full name the end user typed as their signature.","type":"string","minLength":1,"maxLength":200},"date_of_birth":{"description":"The date of birth the end user confirmed when signing. Must equal recipient.date_of_birth.","type":"string","format":"date"},"document_version":{"description":"The version of the consent document the end user was shown.","type":"string","minLength":1,"maxLength":100}}}}}}
```

## The OrderFinancialDTO object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"OrderFinancialDTO":{"description":"Price breakdown including subtotal, tax, shipping, discounts","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"discount_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0}},"required":["total_cents"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]}}}}
```

## The OrderItemResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"OrderItemResponse":{"description":"Individual test kit or product in the order","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"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."},"collection_visit":{"$ref":"#/components/schemas/OrderItemCollectionVisit"},"quantity":{"type":"integer"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]}}}}
```

## The OrderItemCollectionVisit object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]}}}}
```

## The CreateOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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":{"$ref":"#/components/schemas/Currency"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"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."},"collection_visit":{"$ref":"#/components/schemas/OrderItemCollectionVisit"},"quantity":{"type":"integer"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]}}}}
```

## The GetOrderResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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":{"$ref":"#/components/schemas/Currency"},"item_status":{"$ref":"#/components/schemas/ItemStatus"},"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."},"collection_visit":{"$ref":"#/components/schemas/OrderItemCollectionVisit"},"quantity":{"type":"integer"},"results_status":{"type":"string","description":"`results.not_applicable` for a product that never produces a result (a supplement); it never changes and sends no results webhook."},"variant_id":{"type":"string"}},"required":["variant_id","product_type_id","price_per_item_cents","quantity"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]},"OrderItemCollectionVisit":{"description":"The clinician visit Vantage arranged for this item's sample. Present only for a variant with a `collection_visit`.","type":"object","required":["type","status"],"properties":{"type":{"$ref":"#/components/schemas/CollectionVisit"},"status":{"type":"string","description":"Where arranging the visit stands. New statuses may be added; treat an unknown value as in progress.","enum":["booking","requested","booking_failed","awaiting_clinic_invite"]},"scheduling_url":{"type":"string","description":"Where the test-taker books the visit slot. Present once the provider has issued it, which can be shortly after the order is created; reading the order fetches it if it is still missing. Pass it on to the test-taker."}}},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]},"OrderFinancialDTO":{"description":"Price breakdown including subtotal, tax, shipping, discounts","type":"object","properties":{"currency":{"$ref":"#/components/schemas/Currency"},"discount_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0}},"required":["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.10.22"},"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.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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.10.22"},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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.10.22"},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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","results.genome_processing","results.sample_reanalysis","results.reanalysed"],"description":"Non-exhaustive: new statuses may be added without a new API version, so treat an unknown value as an in-progress state. `genome_processing`, `sample_reanalysis` and `reanalysed` are DNA-only."},"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."},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Present on results_ready and reanalysed: the version of the result now served, 1 for the first result and bumped by every re-analysis. Fetch the result again when it changes."},"amended":{"type":"boolean","const":true,"description":"Present only on results_ready for a later corrected release of a result already delivered; fetch the result again."}}}}}}}}
```

## The GetResultsURLResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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"]},"result_type":{"type":"string","description":"How to parse the downloaded file. `fhir_bundle` is a FHIR R4 Bundle (blood tests); `dna_result` is a Terra DNA result, plain JSON (DNA tests), described by the `DNAResult` schema. Non-exhaustive: new representations may be added without a new API version.","enum":["fhir_bundle","dna_result"]},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Version of the result the URL serves: 1 for the first result, bumped by every re-analysis (DNA). Matches `result_version` on the `results.results_ready` and `results.reanalysed` webhooks."}}}}}}
```

## The DNAResult object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAResult":{"description":"The file a `dna_result` download URL serves: one DNA result for one order item, the same shape for every DNA supplier. Not an API response; fetch it from `GET /api/v1/results/{orderItemID}`'s `download_url`.","$ref":"#/components/schemas/dna_result.schema"},"dna_result.schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.tryterra.co/vantage/schemas/dna-result.schema.json","title":"Terra DNA result","description":"One supplier-neutral DNA result per order item. Every supplier adapter produces this shape (DECISIONS.md R1-R13). Every declared key is always present: an unknown value is null and an empty list is [], so a client can tell 'not reported' from a missing key. Enum lists are non-exhaustive: new values are additive.","type":"object","additionalProperties":false,"required":["supplier","result_version","report","supplier_capabilities","screening","findings","raw_data"],"properties":{"supplier":{"description":"The lab supplier that produced the result, e.g. nucleus or selfdecode.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"result_version":{"description":"Starts at 1 and goes up each time the supplier re-analyses the sample (DECISIONS.md L3).","type":"integer","minimum":1},"report":{"$ref":"#/components/schemas/report"},"supplier_capabilities":{"$ref":"#/components/schemas/supplier_capabilities"},"screening":{"description":"One summary per category and method, so a negative result is explicit: a category with tested > 0 and positive = 0 was screened clear, while a category missing here was not screened (DECISIONS.md R8).","type":"array","items":{"$ref":"#/components/schemas/screening"}},"findings":{"description":"Every reported finding. Carrier findings sort first (DECISIONS.md R9).","type":"array","items":{"$ref":"#/components/schemas/finding"}},"raw_data":{"description":"Raw genome files the supplier holds. They never travel through the API (DECISIONS.md R13).","type":"array","items":{"$ref":"#/components/schemas/raw_data"}},"extensions":{"$ref":"#/components/schemas/extensions"}},"$defs":{"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]},"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"nullable_string":{"type":["string","null"]},"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}},"report":{"type":"object","additionalProperties":false,"required":["version","ordering_physician","specimen_received_at","released_at","url"],"properties":{"version":{"description":"The supplier's pipeline or report version.","$ref":"#/components/schemas/nullable_string"},"ordering_physician":{"$ref":"#/components/schemas/nullable_string"},"specimen_received_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"released_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"url":{"description":"Where the full supplier report can be read. Clinical findings that stay with the supplier are read here.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},"supplier_capabilities":{"description":"What this supplier can report at all, so a category missing from screening and findings reads as 'not offered' rather than 'clear'.","type":"object","additionalProperties":false,"required":["categories","methods"],"properties":{"categories":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/category"}},"methods":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/method"}}}},"screening":{"description":"Counts for one category and method. positive and undetermined apply to detected/not-detected screens (carrier, monogenic); above_average, average and below_average apply to banded scores (disease_risk). A count that does not apply is null.","type":"object","additionalProperties":false,"required":["category","method","tested","positive","undetermined","above_average","average","below_average"],"properties":{"category":{"$ref":"#/components/schemas/category"},"method":{"$ref":"#/components/schemas/method"},"tested":{"type":"integer","minimum":0},"positive":{"type":["integer","null"],"minimum":0},"undetermined":{"type":["integer","null"],"minimum":0},"above_average":{"type":["integer","null"],"minimum":0},"average":{"type":["integer","null"],"minimum":0},"below_average":{"type":["integer","null"],"minimum":0}}},"finding":{"type":"object","additionalProperties":false,"required":["id","category","systems","name","description","supplier_label","status","outcome","score","absolute_risk","typical_risk","variants","copy_number","drugs","recommendations","requires_counseling","sensitivity"],"properties":{"id":{"description":"<category>:<the supplier's report id>. Unique within the result and stable across result versions.","type":"string","pattern":"^[a-z_]+:.+$"},"category":{"$ref":"#/components/schemas/category"},"systems":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/system"}},"name":{"type":"string","minLength":1},"description":{"description":"What the condition or trait is, in the supplier's words. Not specific to this person.","$ref":"#/components/schemas/nullable_string"},"supplier_label":{"description":"The supplier's own wording of this person's result, verbatim (e.g. elevated, carrier, Slow metabolizer).","$ref":"#/components/schemas/nullable_string"},"status":{"description":"For detected/not-detected findings (carrier, monogenic, pgx): detected, not_detected, possible (the supplier cannot rule it out) or undetermined. Null for scored findings.","type":["string","null"],"enum":["detected","not_detected","possible","undetermined",null]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/outcome"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/score"},{"type":"null"}]},"absolute_risk":{"description":"This person's risk.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"typical_risk":{"description":"The risk of a typical person of the same sex and age band, for comparison.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/variant"}},"copy_number":{"description":"Copy-number calls. A list because one finding can involve several genes (SMN1 and SMN2 for SMA, HBA1 and HBA2 for alpha thalassemia).","type":"array","items":{"$ref":"#/components/schemas/copy_number"}},"drugs":{"type":"array","items":{"$ref":"#/components/schemas/drug"}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/recommendation"}},"requires_counseling":{"description":"Set by Terra's rules, not the supplier: a detected carrier, a detected clinical (monogenic) finding, or a result the supplier gates behind a counsellor (DECISIONS.md R12).","type":"boolean"},"sensitivity":{"description":"Set when the finding needs the customer's opt-in to be shown (DECISIONS.md R11).","type":["string","null"],"enum":["mental_health",null]},"extensions":{"$ref":"#/components/schemas/extensions"}}},"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}},"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}},"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}},"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}},"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"raw_data":{"type":"object","additionalProperties":false,"required":["format","size_bytes","availability"],"properties":{"format":{"description":"e.g. vcf, sv_vcf, cnv_vcf, cram, fastq, genotype_array.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"size_bytes":{"type":["integer","null"],"minimum":0},"availability":{"description":"api (Terra serves it), portal (the person downloads it from the supplier), on_request (the supplier sends it when asked).","type":"string","enum":["api","portal","on_request"]}}}}},"report":{"type":"object","additionalProperties":false,"required":["version","ordering_physician","specimen_received_at","released_at","url"],"properties":{"version":{"description":"The supplier's pipeline or report version.","$ref":"#/components/schemas/nullable_string"},"ordering_physician":{"$ref":"#/components/schemas/nullable_string"},"specimen_received_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"released_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"url":{"description":"Where the full supplier report can be read. Clinical findings that stay with the supplier are read here.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},"nullable_string":{"type":["string","null"]},"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"supplier_capabilities":{"description":"What this supplier can report at all, so a category missing from screening and findings reads as 'not offered' rather than 'clear'.","type":"object","additionalProperties":false,"required":["categories","methods"],"properties":{"categories":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/category"}},"methods":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/method"}}}},"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]},"screening":{"description":"Counts for one category and method. positive and undetermined apply to detected/not-detected screens (carrier, monogenic); above_average, average and below_average apply to banded scores (disease_risk). A count that does not apply is null.","type":"object","additionalProperties":false,"required":["category","method","tested","positive","undetermined","above_average","average","below_average"],"properties":{"category":{"$ref":"#/components/schemas/category"},"method":{"$ref":"#/components/schemas/method"},"tested":{"type":"integer","minimum":0},"positive":{"type":["integer","null"],"minimum":0},"undetermined":{"type":["integer","null"],"minimum":0},"above_average":{"type":["integer","null"],"minimum":0},"average":{"type":["integer","null"],"minimum":0},"below_average":{"type":["integer","null"],"minimum":0}}},"finding":{"type":"object","additionalProperties":false,"required":["id","category","systems","name","description","supplier_label","status","outcome","score","absolute_risk","typical_risk","variants","copy_number","drugs","recommendations","requires_counseling","sensitivity"],"properties":{"id":{"description":"<category>:<the supplier's report id>. Unique within the result and stable across result versions.","type":"string","pattern":"^[a-z_]+:.+$"},"category":{"$ref":"#/components/schemas/category"},"systems":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/system"}},"name":{"type":"string","minLength":1},"description":{"description":"What the condition or trait is, in the supplier's words. Not specific to this person.","$ref":"#/components/schemas/nullable_string"},"supplier_label":{"description":"The supplier's own wording of this person's result, verbatim (e.g. elevated, carrier, Slow metabolizer).","$ref":"#/components/schemas/nullable_string"},"status":{"description":"For detected/not-detected findings (carrier, monogenic, pgx): detected, not_detected, possible (the supplier cannot rule it out) or undetermined. Null for scored findings.","type":["string","null"],"enum":["detected","not_detected","possible","undetermined",null]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/outcome"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/score"},{"type":"null"}]},"absolute_risk":{"description":"This person's risk.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"typical_risk":{"description":"The risk of a typical person of the same sex and age band, for comparison.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/variant"}},"copy_number":{"description":"Copy-number calls. A list because one finding can involve several genes (SMN1 and SMN2 for SMA, HBA1 and HBA2 for alpha thalassemia).","type":"array","items":{"$ref":"#/components/schemas/copy_number"}},"drugs":{"type":"array","items":{"$ref":"#/components/schemas/drug"}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/recommendation"}},"requires_counseling":{"description":"Set by Terra's rules, not the supplier: a detected carrier, a detected clinical (monogenic) finding, or a result the supplier gates behind a counsellor (DECISIONS.md R12).","type":"boolean"},"sensitivity":{"description":"Set when the finding needs the customer's opt-in to be shown (DECISIONS.md R11).","type":["string","null"],"enum":["mental_health",null]},"extensions":{"$ref":"#/components/schemas/extensions"}}},"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]},"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}},"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}},"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}},"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}},"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}},"raw_data":{"type":"object","additionalProperties":false,"required":["format","size_bytes","availability"],"properties":{"format":{"description":"e.g. vcf, sv_vcf, cnv_vcf, cram, fastq, genotype_array.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"size_bytes":{"type":["integer","null"],"minimum":0},"availability":{"description":"api (Terra serves it), portal (the person downloads it from the supplier), on_request (the supplier sends it when asked).","type":"string","enum":["api","portal","on_request"]}}}}}}
```

## The AcknowledgeResultsResponse object

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

## The Availability object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"Availability":{"type":"string","description":"Whether the item can be ordered right now. `unknown` is served when the supplier has not stated availability.","enum":["unknown","in_stock","out_of_stock"]}}}}
```

## The CollectionMethod object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"CollectionMethod":{"type":"string","description":"How the sample is taken. Omitted when the supplier states a method outside this vocabulary. New methods may be added; treat an unknown value as unstated.","enum":["finger_prick","venous_draw","automatic_capillary","cheek_swab"]}}}}
```

## The CollectionVisit object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]}}}}
```

## The DNAReport object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"DNAReport":{"type":"string","description":"A report category a DNA test's bundle includes; the same vocabulary as the DNA result's finding categories. Non-exhaustive: new categories may be added without a new API version.","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]}}}}
```

## The TurnaroundDays object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"TurnaroundDays":{"type":"object","description":"The supplier's stated lab turnaround in days, from sample received to results. A single stated figure has `min` == `max`.","required":["min","max"],"properties":{"min":{"type":"integer","format":"int32"},"max":{"type":"integer","format":"int32"}}}}}}
```

## The Currency object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]}}}}
```

## The ItemStatus object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ItemStatus":{"type":"string","description":"The kit's shipping status. Omitted until the supplier reports one. Versions before 2026-10-15 serve the integer (1-4, 0 for none) instead.","enum":["pending_shipment","in_transit","delivery_attempted","delivered"]}}}}
```

## The Image object

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

## The Biomarker object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"Biomarker":{"type":"object","description":"One measurement a kit includes.","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable biomarker name."},"code":{"type":"string","description":"The code the result bundle uses for this analyte."},"loinc":{"type":"string","description":"LOINC code for this analyte, when known."}}}}}}
```

## The ProductVariant object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ProductVariant":{"type":"object","required":["name","biomarkers","requires_activation","availability"],"properties":{"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"product_type_id":{"type":"string","description":"Decimal string."},"name":{"type":"string","description":"The variant's name, as the supplier states it."},"description":{"type":"string","description":"The supplier's blurb for this variant. Omitted when it states none."},"collection_method":{"$ref":"#/components/schemas/CollectionMethod"},"collection_visit":{"$ref":"#/components/schemas/CollectionVisit"},"turnaround_days":{"$ref":"#/components/schemas/TurnaroundDays"},"requires_activation":{"type":"boolean","description":"Whether the kit has to be activated before the lab will process its sample. When true, call the kit activation endpoint as part of your flow; the sample is not processed without it."},"availability":{"$ref":"#/components/schemas/Availability"},"biomarkers":{"type":"array","description":"Biomarkers measured by this variant. Empty when the panel is not catalogued or could not be read.","items":{"$ref":"#/components/schemas/Biomarker"}},"reports":{"type":"array","description":"DNA tests only: the reports this variant's bundle includes. A DNA product's variants are report bundles; pick one at order time by its variant id. Omitted for other product types.","items":{"$ref":"#/components/schemas/DNAReport"}},"required_dna_details":{"type":"array","description":"DNA tests only: what an order for this variant must tell Terra about the end user, as JSON paths into the create-order request (recipient.gender_at_birth, or a key of dna). Empty when the variant needs nothing; omitted for other product types. An order missing any of them is rejected with 400 before payment. Non-exhaustive: new values may be added without a new API version.","items":{"type":"string","enum":["recipient.gender_at_birth","dna.health_measurements.height_cm","dna.health_measurements.weight_kg","dna.health_measurements.total_cholesterol_mg_dl","dna.health_measurements.systolic_blood_pressure_mmhg","dna.health_measurements.diastolic_blood_pressure_mmhg","dna.health_measurements.fasting_glucose_mg_dl","dna.health_measurements.hba1c_percent","dna.ancestry","dna.lifestyle","dna.medical_history","dna.eligibility","dna.consent"]}},"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"}},"price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"images":{"description":"This variant's images, in display order. Omitted when it has none.","type":"array","items":{"$ref":"#/components/schemas/Image"}}}},"CollectionMethod":{"type":"string","description":"How the sample is taken. Omitted when the supplier states a method outside this vocabulary. New methods may be added; treat an unknown value as unstated.","enum":["finger_prick","venous_draw","automatic_capillary","cheek_swab"]},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]},"TurnaroundDays":{"type":"object","description":"The supplier's stated lab turnaround in days, from sample received to results. A single stated figure has `min` == `max`.","required":["min","max"],"properties":{"min":{"type":"integer","format":"int32"},"max":{"type":"integer","format":"int32"}}},"Availability":{"type":"string","description":"Whether the item can be ordered right now. `unknown` is served when the supplier has not stated availability.","enum":["unknown","in_stock","out_of_stock"]},"Biomarker":{"type":"object","description":"One measurement a kit includes.","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable biomarker name."},"code":{"type":"string","description":"The code the result bundle uses for this analyte."},"loinc":{"type":"string","description":"LOINC code for this analyte, when known."}}},"DNAReport":{"type":"string","description":"A report category a DNA test's bundle includes; the same vocabulary as the DNA result's finding categories. Non-exhaustive: new categories may be added without a new API version.","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"url":{"type":"string"},"variant_id":{"type":"string","description":"Decimal string."},"width":{"type":"integer","format":"int32"}}}}}}
```

## The Product object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"Product":{"type":"object","required":["variants","availability"],"properties":{"enabled":{"type":"boolean","description":"Present only on ?show_all=true — the caller's per-product curation flag."},"availability":{"$ref":"#/components/schemas/Availability"},"base_price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"type":"string"},"id":{"type":"string","description":"Decimal string."},"images":{"description":"Every image of the product's variants, in display order.","type":"array","items":{"$ref":"#/components/schemas/Image"}},"name":{"type":"string"},"product_type_id":{"type":"string","description":"Decimal string."},"variants":{"type":"array","description":"The product's variants, on the same curation rules as GET /products/{id}/variants. Empty when the product has none.","items":{"$ref":"#/components/schemas/ProductVariant"}}}},"Availability":{"type":"string","description":"Whether the item can be ordered right now. `unknown` is served when the supplier has not stated availability.","enum":["unknown","in_stock","out_of_stock"]},"Currency":{"type":"string","description":"ISO 4217 alphabetic currency code. Omitted when the stored currency is not one of these. Versions before 2026-10-15 serve the ISO 4217 numeric code (840, 978, 826) instead.","enum":["USD","EUR","GBP"]},"Image":{"type":"object","properties":{"alt_text":{"type":"string"},"display_order":{"type":"integer","format":"int32"},"height":{"type":"integer","format":"int32"},"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"url":{"type":"string"},"variant_id":{"type":"string","description":"Decimal string."},"width":{"type":"integer","format":"int32"}}},"ProductVariant":{"type":"object","required":["name","biomarkers","requires_activation","availability"],"properties":{"id":{"type":"string","description":"Decimal string."},"product_id":{"type":"string","description":"Decimal string."},"product_type_id":{"type":"string","description":"Decimal string."},"name":{"type":"string","description":"The variant's name, as the supplier states it."},"description":{"type":"string","description":"The supplier's blurb for this variant. Omitted when it states none."},"collection_method":{"$ref":"#/components/schemas/CollectionMethod"},"collection_visit":{"$ref":"#/components/schemas/CollectionVisit"},"turnaround_days":{"$ref":"#/components/schemas/TurnaroundDays"},"requires_activation":{"type":"boolean","description":"Whether the kit has to be activated before the lab will process its sample. When true, call the kit activation endpoint as part of your flow; the sample is not processed without it."},"availability":{"$ref":"#/components/schemas/Availability"},"biomarkers":{"type":"array","description":"Biomarkers measured by this variant. Empty when the panel is not catalogued or could not be read.","items":{"$ref":"#/components/schemas/Biomarker"}},"reports":{"type":"array","description":"DNA tests only: the reports this variant's bundle includes. A DNA product's variants are report bundles; pick one at order time by its variant id. Omitted for other product types.","items":{"$ref":"#/components/schemas/DNAReport"}},"required_dna_details":{"type":"array","description":"DNA tests only: what an order for this variant must tell Terra about the end user, as JSON paths into the create-order request (recipient.gender_at_birth, or a key of dna). Empty when the variant needs nothing; omitted for other product types. An order missing any of them is rejected with 400 before payment. Non-exhaustive: new values may be added without a new API version.","items":{"type":"string","enum":["recipient.gender_at_birth","dna.health_measurements.height_cm","dna.health_measurements.weight_kg","dna.health_measurements.total_cholesterol_mg_dl","dna.health_measurements.systolic_blood_pressure_mmhg","dna.health_measurements.diastolic_blood_pressure_mmhg","dna.health_measurements.fasting_glucose_mg_dl","dna.health_measurements.hba1c_percent","dna.ancestry","dna.lifestyle","dna.medical_history","dna.eligibility","dna.consent"]}},"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"}},"price_cents":{"type":"integer","format":"int32"},"currency":{"$ref":"#/components/schemas/Currency"},"images":{"description":"This variant's images, in display order. Omitted when it has none.","type":"array","items":{"$ref":"#/components/schemas/Image"}}}},"CollectionMethod":{"type":"string","description":"How the sample is taken. Omitted when the supplier states a method outside this vocabulary. New methods may be added; treat an unknown value as unstated.","enum":["finger_prick","venous_draw","automatic_capillary","cheek_swab"]},"CollectionVisit":{"type":"string","description":"The clinician visit the sample is taken at. Omitted for a self-collected kit. New visits may be added; treat an unknown value as a visit you cannot offer.","enum":["home_phlebotomy","clinic"]},"TurnaroundDays":{"type":"object","description":"The supplier's stated lab turnaround in days, from sample received to results. A single stated figure has `min` == `max`.","required":["min","max"],"properties":{"min":{"type":"integer","format":"int32"},"max":{"type":"integer","format":"int32"}}},"Biomarker":{"type":"object","description":"One measurement a kit includes.","required":["name"],"properties":{"name":{"type":"string","description":"Human-readable biomarker name."},"code":{"type":"string","description":"The code the result bundle uses for this analyte."},"loinc":{"type":"string","description":"LOINC code for this analyte, when known."}}},"DNAReport":{"type":"string","description":"A report category a DNA test's bundle includes; the same vocabulary as the DNA result's finding categories. Non-exhaustive: new categories may be added without a new API version.","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]}}}}
```

## The ProductType object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ProductType":{"type":"object","properties":{"description":{"type":"string"},"id":{"type":"string","description":"Decimal string."},"name":{"type":"string"}}}}}}
```

## The ListLabsResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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,"description":"State, province or county. For US addresses (`country_code` US) this must be the two-letter USPS state code, for example `TX`."},"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.10.22"},"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 ResendWebhookEventRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ResendWebhookEventRequest":{"type":"object","required":["event_id"],"properties":{"event_id":{"type":"string","description":"The `event_id` of the delivered webhook (also its `X-Terra-Trace-Id`)."},"event_type":{"type":"string","description":"Optional; when set it must match the stored event's type."}}}}}}
```

## The ResendWebhookEventResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ResendWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."}}}}}}
```

## The ResendWebhookEventDryRunResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"ResendWebhookEventDryRunResponse":{"type":"object","required":["dry_run","would","preview"],"properties":{"dry_run":{"type":"boolean","const":true},"would":{"type":"string","const":"resend"},"preview":{"$ref":"#/components/schemas/ResendWebhookEventResponse"}}},"ResendWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."}}}}}}
```

## The GenerateWebhookEventRequest object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"GenerateWebhookEventRequest":{"type":"object","required":["event_type"],"properties":{"event_type":{"type":"string","enum":["order.status_changed","order_item.results_status_change"]},"status":{"type":"string","description":"The `data.status` (for order.status_changed) or `data.results_status` (for order_item.results_status_change) the event carries, from that webhook's enum. Defaults to `order.delivery_fulfilled` and `results.results_ready`."}}}}}}
```

## The GenerateWebhookEventResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"GenerateWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched","payload"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."},"payload":{"description":"The latest-shape webhook body.","oneOf":[{"$ref":"#/components/schemas/OrderStatusChangedEvent"},{"$ref":"#/components/schemas/OrderItemResultsStatusChangedEvent"}]}}},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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."}}}}},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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","results.genome_processing","results.sample_reanalysis","results.reanalysed"],"description":"Non-exhaustive: new statuses may be added without a new API version, so treat an unknown value as an in-progress state. `genome_processing`, `sample_reanalysis` and `reanalysed` are DNA-only."},"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."},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Present on results_ready and reanalysed: the version of the result now served, 1 for the first result and bumped by every re-analysis. Fetch the result again when it changes."},"amended":{"type":"boolean","const":true,"description":"Present only on results_ready for a later corrected release of a result already delivered; fetch the result again."}}}}}}}}
```

## The GenerateWebhookEventDryRunResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"GenerateWebhookEventDryRunResponse":{"type":"object","required":["dry_run","would","preview"],"properties":{"dry_run":{"type":"boolean","const":true},"would":{"type":"string","const":"dispatch"},"preview":{"$ref":"#/components/schemas/GenerateWebhookEventResponse"}}},"GenerateWebhookEventResponse":{"type":"object","required":["event_id","event_type","dispatched","payload"],"properties":{"event_id":{"type":"string"},"event_type":{"type":"string"},"dispatched":{"type":"boolean","description":"True when the event was queued; false in a dry-run preview."},"payload":{"description":"The latest-shape webhook body.","oneOf":[{"$ref":"#/components/schemas/OrderStatusChangedEvent"},{"$ref":"#/components/schemas/OrderItemResultsStatusChangedEvent"}]}}},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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."}}}}},"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."},"test":{"type":"boolean","const":true,"description":"Present only on events from `POST /api/v1/webhook-events/generate`, which describe no real order."},"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","results.genome_processing","results.sample_reanalysis","results.reanalysed"],"description":"Non-exhaustive: new statuses may be added without a new API version, so treat an unknown value as an in-progress state. `genome_processing`, `sample_reanalysis` and `reanalysed` are DNA-only."},"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."},"result_version":{"type":"integer","format":"int32","minimum":1,"description":"Present on results_ready and reanalysed: the version of the result now served, 1 for the first result and bumped by every re-analysis. Fetch the result again when it changes."},"amended":{"type":"boolean","const":true,"description":"Present only on results_ready for a later corrected release of a result already delivered; fetch the result again."}}}}}}}}
```

## The WebhookEventProblem object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"WebhookEventProblem":{"description":"RFC 7807 problem from the webhook-events operations, with a code to branch on and a remediation to show. (Flat rather than an allOf over ProblemDetail: the conformance gate seals declared objects.)","type":"object","required":["code","detail","status","title","type"],"properties":{"detail":{"type":"string"},"instance":{"type":"string"},"status":{"type":"integer"},"title":{"type":"string"},"type":{"type":"string"},"code":{"type":"string","enum":["not_found","event_not_resendable","webhook_url_missing"]},"remediation":{"type":"string"}}}}}}
```

## The WebhookDeliveriesResponse object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"WebhookDeliveriesResponse":{"type":"object","description":"One page of webhook delivery outcomes, newest first. Versions before 2026-10-15 serve the items under `deliveries` instead of `data`, no `has_more`, and omit `next_cursor` on the last page.","required":["data","has_more","next_cursor"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"has_more":{"type":"boolean","description":"Whether another page follows."},"next_cursor":{"type":["string","null"],"description":"Pass as ?cursor= for the next page; null 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.10.22"},"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"}}}}}}
```

## The nullable\_string object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"nullable_string":{"type":["string","null"]}}}}
```

## The date\_or\_date\_time object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]}}}}
```

## The category object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]}}}}
```

## The method object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]}}}}
```

## The system object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]}}}}
```

## The outcome object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}}}}}
```

## The score object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}}}}}
```

## The risk object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}}}}}
```

## The variant object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"nullable_string":{"type":["string","null"]}}}}
```

## The copy\_number object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}}}}}
```

## The drug object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"nullable_string":{"type":["string","null"]}}}}
```

## The recommendation object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"nullable_string":{"type":["string","null"]}}}}
```

## The extensions object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}}}}}
```

## The report object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"report":{"type":"object","additionalProperties":false,"required":["version","ordering_physician","specimen_received_at","released_at","url"],"properties":{"version":{"description":"The supplier's pipeline or report version.","$ref":"#/components/schemas/nullable_string"},"ordering_physician":{"$ref":"#/components/schemas/nullable_string"},"specimen_received_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"released_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"url":{"description":"Where the full supplier report can be read. Clinical findings that stay with the supplier are read here.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},"nullable_string":{"type":["string","null"]},"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]}}}}
```

## The supplier\_capabilities object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"supplier_capabilities":{"description":"What this supplier can report at all, so a category missing from screening and findings reads as 'not offered' rather than 'clear'.","type":"object","additionalProperties":false,"required":["categories","methods"],"properties":{"categories":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/category"}},"methods":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/method"}}}},"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]}}}}
```

## The screening object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"screening":{"description":"Counts for one category and method. positive and undetermined apply to detected/not-detected screens (carrier, monogenic); above_average, average and below_average apply to banded scores (disease_risk). A count that does not apply is null.","type":"object","additionalProperties":false,"required":["category","method","tested","positive","undetermined","above_average","average","below_average"],"properties":{"category":{"$ref":"#/components/schemas/category"},"method":{"$ref":"#/components/schemas/method"},"tested":{"type":"integer","minimum":0},"positive":{"type":["integer","null"],"minimum":0},"undetermined":{"type":["integer","null"],"minimum":0},"above_average":{"type":["integer","null"],"minimum":0},"average":{"type":["integer","null"],"minimum":0},"below_average":{"type":["integer","null"],"minimum":0}}},"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]}}}}
```

## The finding object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"finding":{"type":"object","additionalProperties":false,"required":["id","category","systems","name","description","supplier_label","status","outcome","score","absolute_risk","typical_risk","variants","copy_number","drugs","recommendations","requires_counseling","sensitivity"],"properties":{"id":{"description":"<category>:<the supplier's report id>. Unique within the result and stable across result versions.","type":"string","pattern":"^[a-z_]+:.+$"},"category":{"$ref":"#/components/schemas/category"},"systems":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/system"}},"name":{"type":"string","minLength":1},"description":{"description":"What the condition or trait is, in the supplier's words. Not specific to this person.","$ref":"#/components/schemas/nullable_string"},"supplier_label":{"description":"The supplier's own wording of this person's result, verbatim (e.g. elevated, carrier, Slow metabolizer).","$ref":"#/components/schemas/nullable_string"},"status":{"description":"For detected/not-detected findings (carrier, monogenic, pgx): detected, not_detected, possible (the supplier cannot rule it out) or undetermined. Null for scored findings.","type":["string","null"],"enum":["detected","not_detected","possible","undetermined",null]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/outcome"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/score"},{"type":"null"}]},"absolute_risk":{"description":"This person's risk.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"typical_risk":{"description":"The risk of a typical person of the same sex and age band, for comparison.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/variant"}},"copy_number":{"description":"Copy-number calls. A list because one finding can involve several genes (SMN1 and SMN2 for SMA, HBA1 and HBA2 for alpha thalassemia).","type":"array","items":{"$ref":"#/components/schemas/copy_number"}},"drugs":{"type":"array","items":{"$ref":"#/components/schemas/drug"}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/recommendation"}},"requires_counseling":{"description":"Set by Terra's rules, not the supplier: a detected carrier, a detected clinical (monogenic) finding, or a result the supplier gates behind a counsellor (DECISIONS.md R12).","type":"boolean"},"sensitivity":{"description":"Set when the finding needs the customer's opt-in to be shown (DECISIONS.md R11).","type":["string","null"],"enum":["mental_health",null]},"extensions":{"$ref":"#/components/schemas/extensions"}}},"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]},"nullable_string":{"type":["string","null"]},"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}},"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}},"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}},"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}},"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}}}}}
```

## The raw\_data object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"raw_data":{"type":"object","additionalProperties":false,"required":["format","size_bytes","availability"],"properties":{"format":{"description":"e.g. vcf, sv_vcf, cnv_vcf, cram, fastq, genotype_array.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"size_bytes":{"type":["integer","null"],"minimum":0},"availability":{"description":"api (Terra serves it), portal (the person downloads it from the supplier), on_request (the supplier sends it when asked).","type":"string","enum":["api","portal","on_request"]}}}}}}
```

## The dna\_result.schema object

```json
{"openapi":"3.1.0","info":{"title":"Terra Vantage API","version":"2026.10.22"},"components":{"schemas":{"dna_result.schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.tryterra.co/vantage/schemas/dna-result.schema.json","title":"Terra DNA result","description":"One supplier-neutral DNA result per order item. Every supplier adapter produces this shape (DECISIONS.md R1-R13). Every declared key is always present: an unknown value is null and an empty list is [], so a client can tell 'not reported' from a missing key. Enum lists are non-exhaustive: new values are additive.","type":"object","additionalProperties":false,"required":["supplier","result_version","report","supplier_capabilities","screening","findings","raw_data"],"properties":{"supplier":{"description":"The lab supplier that produced the result, e.g. nucleus or selfdecode.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"result_version":{"description":"Starts at 1 and goes up each time the supplier re-analyses the sample (DECISIONS.md L3).","type":"integer","minimum":1},"report":{"$ref":"#/components/schemas/report"},"supplier_capabilities":{"$ref":"#/components/schemas/supplier_capabilities"},"screening":{"description":"One summary per category and method, so a negative result is explicit: a category with tested > 0 and positive = 0 was screened clear, while a category missing here was not screened (DECISIONS.md R8).","type":"array","items":{"$ref":"#/components/schemas/screening"}},"findings":{"description":"Every reported finding. Carrier findings sort first (DECISIONS.md R9).","type":"array","items":{"$ref":"#/components/schemas/finding"}},"raw_data":{"description":"Raw genome files the supplier holds. They never travel through the API (DECISIONS.md R13).","type":"array","items":{"$ref":"#/components/schemas/raw_data"}},"extensions":{"$ref":"#/components/schemas/extensions"}},"$defs":{"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]},"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"nullable_string":{"type":["string","null"]},"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}},"report":{"type":"object","additionalProperties":false,"required":["version","ordering_physician","specimen_received_at","released_at","url"],"properties":{"version":{"description":"The supplier's pipeline or report version.","$ref":"#/components/schemas/nullable_string"},"ordering_physician":{"$ref":"#/components/schemas/nullable_string"},"specimen_received_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"released_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"url":{"description":"Where the full supplier report can be read. Clinical findings that stay with the supplier are read here.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},"supplier_capabilities":{"description":"What this supplier can report at all, so a category missing from screening and findings reads as 'not offered' rather than 'clear'.","type":"object","additionalProperties":false,"required":["categories","methods"],"properties":{"categories":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/category"}},"methods":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/method"}}}},"screening":{"description":"Counts for one category and method. positive and undetermined apply to detected/not-detected screens (carrier, monogenic); above_average, average and below_average apply to banded scores (disease_risk). A count that does not apply is null.","type":"object","additionalProperties":false,"required":["category","method","tested","positive","undetermined","above_average","average","below_average"],"properties":{"category":{"$ref":"#/components/schemas/category"},"method":{"$ref":"#/components/schemas/method"},"tested":{"type":"integer","minimum":0},"positive":{"type":["integer","null"],"minimum":0},"undetermined":{"type":["integer","null"],"minimum":0},"above_average":{"type":["integer","null"],"minimum":0},"average":{"type":["integer","null"],"minimum":0},"below_average":{"type":["integer","null"],"minimum":0}}},"finding":{"type":"object","additionalProperties":false,"required":["id","category","systems","name","description","supplier_label","status","outcome","score","absolute_risk","typical_risk","variants","copy_number","drugs","recommendations","requires_counseling","sensitivity"],"properties":{"id":{"description":"<category>:<the supplier's report id>. Unique within the result and stable across result versions.","type":"string","pattern":"^[a-z_]+:.+$"},"category":{"$ref":"#/components/schemas/category"},"systems":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/system"}},"name":{"type":"string","minLength":1},"description":{"description":"What the condition or trait is, in the supplier's words. Not specific to this person.","$ref":"#/components/schemas/nullable_string"},"supplier_label":{"description":"The supplier's own wording of this person's result, verbatim (e.g. elevated, carrier, Slow metabolizer).","$ref":"#/components/schemas/nullable_string"},"status":{"description":"For detected/not-detected findings (carrier, monogenic, pgx): detected, not_detected, possible (the supplier cannot rule it out) or undetermined. Null for scored findings.","type":["string","null"],"enum":["detected","not_detected","possible","undetermined",null]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/outcome"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/score"},{"type":"null"}]},"absolute_risk":{"description":"This person's risk.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"typical_risk":{"description":"The risk of a typical person of the same sex and age band, for comparison.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/variant"}},"copy_number":{"description":"Copy-number calls. A list because one finding can involve several genes (SMN1 and SMN2 for SMA, HBA1 and HBA2 for alpha thalassemia).","type":"array","items":{"$ref":"#/components/schemas/copy_number"}},"drugs":{"type":"array","items":{"$ref":"#/components/schemas/drug"}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/recommendation"}},"requires_counseling":{"description":"Set by Terra's rules, not the supplier: a detected carrier, a detected clinical (monogenic) finding, or a result the supplier gates behind a counsellor (DECISIONS.md R12).","type":"boolean"},"sensitivity":{"description":"Set when the finding needs the customer's opt-in to be shown (DECISIONS.md R11).","type":["string","null"],"enum":["mental_health",null]},"extensions":{"$ref":"#/components/schemas/extensions"}}},"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}},"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}},"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}},"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}},"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"raw_data":{"type":"object","additionalProperties":false,"required":["format","size_bytes","availability"],"properties":{"format":{"description":"e.g. vcf, sv_vcf, cnv_vcf, cram, fastq, genotype_array.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"size_bytes":{"type":["integer","null"],"minimum":0},"availability":{"description":"api (Terra serves it), portal (the person downloads it from the supplier), on_request (the supplier sends it when asked).","type":"string","enum":["api","portal","on_request"]}}}}},"report":{"type":"object","additionalProperties":false,"required":["version","ordering_physician","specimen_received_at","released_at","url"],"properties":{"version":{"description":"The supplier's pipeline or report version.","$ref":"#/components/schemas/nullable_string"},"ordering_physician":{"$ref":"#/components/schemas/nullable_string"},"specimen_received_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"released_at":{"anyOf":[{"$ref":"#/components/schemas/date_or_date_time"},{"type":"null"}]},"url":{"description":"Where the full supplier report can be read. Clinical findings that stay with the supplier are read here.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},"nullable_string":{"type":["string","null"]},"date_or_date_time":{"description":"An RFC 3339 date-time, or a full date when the supplier reports only the day.","anyOf":[{"type":"string","format":"date-time"},{"type":"string","format":"date"}]},"supplier_capabilities":{"description":"What this supplier can report at all, so a category missing from screening and findings reads as 'not offered' rather than 'clear'.","type":"object","additionalProperties":false,"required":["categories","methods"],"properties":{"categories":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/category"}},"methods":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/method"}}}},"category":{"description":"What kind of finding (DECISIONS.md R4).","type":"string","enum":["carrier","monogenic","disease_risk","pgx","trait","longevity","ancestry"]},"method":{"description":"How a finding was screened: snv_indel (sequence variants), cnv (copy number), repeat_expansion, polygenic_score, star_allele (pharmacogenomic haplotypes).","type":"string","enum":["snv_indel","cnv","repeat_expansion","polygenic_score","star_allele"]},"screening":{"description":"Counts for one category and method. positive and undetermined apply to detected/not-detected screens (carrier, monogenic); above_average, average and below_average apply to banded scores (disease_risk). A count that does not apply is null.","type":"object","additionalProperties":false,"required":["category","method","tested","positive","undetermined","above_average","average","below_average"],"properties":{"category":{"$ref":"#/components/schemas/category"},"method":{"$ref":"#/components/schemas/method"},"tested":{"type":"integer","minimum":0},"positive":{"type":["integer","null"],"minimum":0},"undetermined":{"type":["integer","null"],"minimum":0},"above_average":{"type":["integer","null"],"minimum":0},"average":{"type":["integer","null"],"minimum":0},"below_average":{"type":["integer","null"],"minimum":0}}},"finding":{"type":"object","additionalProperties":false,"required":["id","category","systems","name","description","supplier_label","status","outcome","score","absolute_risk","typical_risk","variants","copy_number","drugs","recommendations","requires_counseling","sensitivity"],"properties":{"id":{"description":"<category>:<the supplier's report id>. Unique within the result and stable across result versions.","type":"string","pattern":"^[a-z_]+:.+$"},"category":{"$ref":"#/components/schemas/category"},"systems":{"type":"array","uniqueItems":true,"items":{"$ref":"#/components/schemas/system"}},"name":{"type":"string","minLength":1},"description":{"description":"What the condition or trait is, in the supplier's words. Not specific to this person.","$ref":"#/components/schemas/nullable_string"},"supplier_label":{"description":"The supplier's own wording of this person's result, verbatim (e.g. elevated, carrier, Slow metabolizer).","$ref":"#/components/schemas/nullable_string"},"status":{"description":"For detected/not-detected findings (carrier, monogenic, pgx): detected, not_detected, possible (the supplier cannot rule it out) or undetermined. Null for scored findings.","type":["string","null"],"enum":["detected","not_detected","possible","undetermined",null]},"outcome":{"anyOf":[{"$ref":"#/components/schemas/outcome"},{"type":"null"}]},"score":{"anyOf":[{"$ref":"#/components/schemas/score"},{"type":"null"}]},"absolute_risk":{"description":"This person's risk.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"typical_risk":{"description":"The risk of a typical person of the same sex and age band, for comparison.","anyOf":[{"$ref":"#/components/schemas/risk"},{"type":"null"}]},"variants":{"type":"array","items":{"$ref":"#/components/schemas/variant"}},"copy_number":{"description":"Copy-number calls. A list because one finding can involve several genes (SMN1 and SMN2 for SMA, HBA1 and HBA2 for alpha thalassemia).","type":"array","items":{"$ref":"#/components/schemas/copy_number"}},"drugs":{"type":"array","items":{"$ref":"#/components/schemas/drug"}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/recommendation"}},"requires_counseling":{"description":"Set by Terra's rules, not the supplier: a detected carrier, a detected clinical (monogenic) finding, or a result the supplier gates behind a counsellor (DECISIONS.md R12).","type":"boolean"},"sensitivity":{"description":"Set when the finding needs the customer's opt-in to be shown (DECISIONS.md R11).","type":["string","null"],"enum":["mental_health",null]},"extensions":{"$ref":"#/components/schemas/extensions"}}},"system":{"description":"A body system the finding touches (DECISIONS.md R5).","type":"string","enum":["performance","metabolic","cognitive","immune","detox","hormone"]},"outcome":{"description":"The supplier's band for this result: a display label, a colour, and its position among the supplier's bands (1 is the lowest).","type":"object","additionalProperties":false,"required":["label","color","position","of"],"properties":{"label":{"type":"string","minLength":1},"color":{"description":"Terra's semantic colour for the band: green (favourable), amber (watch), red (unfavourable), grey (neutral).","type":"string","enum":["green","amber","red","grey"]},"position":{"type":"integer","minimum":1},"of":{"type":"integer","minimum":1}}},"score":{"type":"object","additionalProperties":false,"required":["value","type","ancestry_adjusted"],"if":{"properties":{"type":{"enum":["percentile","percentage"]}},"required":["type"]},"then":{"properties":{"value":{"minimum":0,"maximum":100}}},"properties":{"value":{"type":"number"},"type":{"description":"percentile (0-100), percentage (0-100), or z_score (standard deviations from the population mean).","type":"string","enum":["percentile","percentage","z_score"]},"ancestry_adjusted":{"description":"Whether the score is standardised against the person's genetic ancestry. Null when the supplier does not say.","type":["boolean","null"]}}},"risk":{"type":"object","additionalProperties":false,"required":["value","unit","applies_to"],"if":{"properties":{"unit":{"const":"fraction"}},"required":["unit"]},"then":{"properties":{"value":{"maximum":1}}},"else":{"properties":{"value":{"maximum":100}}},"properties":{"value":{"type":"number","minimum":0},"unit":{"description":"fraction (0-1) or percent (0-100).","type":"string","enum":["fraction","percent"]},"applies_to":{"description":"The horizon the risk covers, e.g. lifetime or 10_years.","type":"string","minLength":1}}},"variant":{"type":"object","additionalProperties":false,"required":["rsid","genotype","effect_allele","gene","transcript","hgvs_c","hgvs_p","genomic_location","zygosity","inheritance","classification"],"properties":{"rsid":{"anyOf":[{"type":"string","pattern":"^rs[0-9]+$"},{"type":"null"}]},"genotype":{"description":"This person's alleles, e.g. C/T.","$ref":"#/components/schemas/nullable_string"},"effect_allele":{"description":"The allele that raises the score or risk.","$ref":"#/components/schemas/nullable_string"},"gene":{"$ref":"#/components/schemas/nullable_string"},"transcript":{"$ref":"#/components/schemas/nullable_string"},"hgvs_c":{"$ref":"#/components/schemas/nullable_string"},"hgvs_p":{"$ref":"#/components/schemas/nullable_string"},"genomic_location":{"description":"chromosome:position:ref-alt as the supplier reports it (GRCh38 unless the supplier says otherwise).","$ref":"#/components/schemas/nullable_string"},"zygosity":{"type":["string","null"],"enum":["heterozygous","homozygous","hemizygous",null]},"inheritance":{"type":["string","null"],"enum":["autosomal_dominant","autosomal_recessive","x_linked","x_linked_dominant","x_linked_recessive","mitochondrial",null]},"classification":{"description":"ACMG/AMP tier.","type":["string","null"],"enum":["pathogenic","likely_pathogenic","uncertain_significance","likely_benign","benign",null]}}},"copy_number":{"type":"object","additionalProperties":false,"required":["gene","copies"],"properties":{"gene":{"type":"string","minLength":1},"copies":{"type":"integer","minimum":0}}},"drug":{"type":"object","additionalProperties":false,"required":["name","guidance","source"],"properties":{"name":{"type":"string","minLength":1},"guidance":{"$ref":"#/components/schemas/nullable_string"},"source":{"description":"The guideline the guidance comes from, e.g. CPIC.","$ref":"#/components/schemas/nullable_string"}}},"recommendation":{"type":"object","additionalProperties":false,"required":["text","kind"],"properties":{"text":{"type":"string","minLength":1},"kind":{"description":"The supplier's grouping, e.g. lifestyle, diet, supplement, screening.","$ref":"#/components/schemas/nullable_string"}}},"extensions":{"description":"Supplier-only extras, keyed by supplier name (DECISIONS.md R6). Their shape is the supplier's and is not covered by API versioning.","type":"object","propertyNames":{"pattern":"^[a-z][a-z0-9_]*$"},"additionalProperties":{"type":"object"}},"raw_data":{"type":"object","additionalProperties":false,"required":["format","size_bytes","availability"],"properties":{"format":{"description":"e.g. vcf, sv_vcf, cnv_vcf, cram, fastq, genotype_array.","type":"string","pattern":"^[a-z][a-z0-9_]*$"},"size_bytes":{"type":["integer","null"],"minimum":0},"availability":{"description":"api (Terra serves it), portal (the person downloads it from the supplier), on_request (the supplier sends it when asked).","type":"string","enum":["api","portal","on_request"]}}}}}}
```