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

# Best practices

## Webhook handling

* **Verify the signature on every delivery** before parsing the body ([Webhooks](/vantage-api-docs/documentation/webhooks.md#signature-verification)). Use the raw request bytes and remember the timestamp is Unix **seconds**.
* **Return 2xx fast.** Persist the event and process asynchronously; Terra times out deliveries after 10 seconds and treats non-2xx as failure.
* **Deduplicate on `event_id`.** Delivery is at-least-once; you will occasionally see the same event twice.
* **Don't assume ordering.** A delivery can be stale by the time it arrives - never let an older status overwrite a newer one you've already recorded. When you must establish the authoritative current state, read `status_history` from `GET /api/v1/orders/{orderID}`.
* **Reconcile periodically.** A daily sweep of `GET /api/v1/orders?missing=true` (delivered orders still waiting on results) and `GET /api/v1/results?status=results.results_ready` (ready but perhaps unacknowledged) catches anything a missed webhook would otherwise hide.

## Placing orders

* **Generate a unique `client_order_reference_id` per order** and store the mapping to `order_id`. It is your reconciliation key across webhooks, REST reads, and support requests.
* **Send an `Idempotency-Key` on order creation.** A unique key per order attempt makes retries safe: the same key + same body replays the original result instead of double-ordering (and double-charging). Keep `client_order_reference_id` as your reconciliation key - it is not a dedupe key. If you can't send the header, don't blind-retry ambiguous failures (timeout, `5xx`): first list recent orders (`GET /api/v1/orders?since=...`) and check whether your `client_order_reference_id` already appears.
* **Check `available_collection_types` on the variant** before offering `AT_HOME` vs `GO_TO_LAB` to a user, and send the matching address field (`shipping_address` vs `requested_lab_address`).
* **Validate phone numbers with their country code** client-side; the API rejects mismatches with a field-level validation error ([Errors](/vantage-api-docs/documentation/errors.md#validation-errors-on-order-creation)).

## Handling identifiers

* **Store all Vantage IDs as strings.** `order_id`, `order_item_id`, `recipient_id`, `test_taker_id` are 64-bit values serialized as JSON strings; parsing them as doubles (JavaScript's default for numbers) corrupts them.
* **Key your results flow on `order_item_id`**, not `order_id` - activation, result statuses, downloads, and acknowledgment are all per item.
* **Capture `test_taker_id` when it first appears** (the `results.kit_activated` webhook, or any later result webhook). You need it to fetch and acknowledge results. If you miss it, recover it from `GET /api/v1/orders/{orderID}` under `items[].test_taker_ids`.

## Delivering results to your users

* **Re-mint download URLs on demand.** The presigned `download_url` expires after 15 minutes - fetch it when the user opens the result, never store it.
* **Make acknowledgment an explicit user action.** Call the acknowledge endpoint when the user has actually viewed their results - a button or checkbox - never automatically on retrieval. This is a compliance requirement, not a technicality ([Acknowledging Results](/vantage-api-docs/important-information/acknowledging-results.md)).
* **Treat escalations as urgent.** On `results.escalation_raised`, surface the result to the user promptly and acknowledge before `acknowledgment_due_by`; unacknowledged escalations can trigger direct outreach to the patient by medical teams.
* **Handle the failure paths.** Build product flows for `results.sample_rejected` (offer a replacement kit) and `results.lab_processing_error` - they happen in production.

## Environments

* **Build against sandbox first**; it delivers the same signed webhooks as production. Use the [simulate endpoint](/vantage-api-docs/getting-started/working-with-sandbox.md#option-1-the-simulate-endpoint) in automated tests - it is deterministic and covers failure paths.
* **Remember sandbox and production hold separate webhook URLs**, and `supplier_item_id` appears in sandbox webhook payloads only.
* Before launch, walk the [Going to production](/vantage-api-docs/important-information/going-to-production.md) checklist.