# Working with Sandbox * To familiarise yourself with the API, we provide a **comprehensive sandbox environment** where you can simulate ordering kits from different suppliers * Below we will simulate an ordering a kit + end user's flow from a supplier that supports a 2 step activation process {% hint style="danger" %} ### **Kit Activation in Sandbox** Certain suppliers require end-users to activate the kit themselves (i.e scanning a QR code on the kit). \ For **Sandbox** you will have to mimic this step by calling the `api/v1/orders/activate` endpoint (as shown below) {% endhint %} {% hint style="success" %} You will receive automated webhooks in sandbox to your configured endpoint {% endhint %} ### 1. Order a test kit * Follow the steps as outlined in [Ordering your first test](/vantage-api-docs/getting-started/ordering-your-first-test.md) within the sandbox ### 2. Receiving supplier's item ID * After ordering a kit you should receive the following webhook: * Notice how `supplier_item_id` is only available when working in sandbox {% tabs %} {% tab title="Sandbox" %} ```javascript { "data": { "order_id": 249956252111773696, "status": "fulfillment.delivery_fulfilled", "supplier_item_id": "249602021676720128", "tracking_number": "KnD3d5PMZyq5ulNcWkrq" }, "event_id": 249956485092777984, "event_type": "order.status_changed", "timestamp": 1763661470 } ``` {% endtab %} {% tab title="Production" %} ```python { "data": { "order_id": 249956252111773696, "status": "fulfillment.delivery_fulfilled", "tracking_number": "KnD3d5PMZyq5ulNcWkrq" }, "event_id": 249956485092777984, "event_type": "order.status_changed", "timestamp": 1763661470 } ``` {% endtab %} {% endtabs %} ### 3. Activating the kit * For suppliers who support 2 step activation, on each kit there will be a QR code that embeds the following URL which links to prod * To simulate scanning the QR code: * Replace the production domain with sandbox domain * Paste `supplier_item_id` as the query parameter {% tabs %} {% tab title="Sandbox" %} ```hurl https://vantage-sandbox.tryterra.co/api/v1/orders/activate?kit_id=249602021676720128 ``` {% endtab %} {% tab title="Production" %} ```hurl https://vantage.tryterra.co/api/v1/orders/activate?kit_id=249602021676720128 ``` {% endtab %} {% endtabs %} * You should be redirected to the page below - fill out the details and activate your kit! ### 4. Lab received kit + results
### 4. Lab received kit + Results * At this point your end user will take the test and post it to the lab to be analysed. Upon arriving at the lab, a webhook will be sent to you. * Results will be available shortly after arrival of the kit at the lab, with a second webhook sent. * To simulate this, the sandbox environment automatically sends the following two webhooks after successful kit activation, sent at 1-2 minute intervals. * **N.B** There is also a change you will get a `results.sample_rejected` webhook {% tabs %} {% tab title="Lab Processing" %} ```json { "data": { "order_id": 249956252111773696, "order_item_id": 249956252111773699, "results_status": "results.sample_processing_in_lab", "test_taker": { "test_taker_id": "257837964552478720", "country_code": 1, "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone_number": 4155551234 }, "variant_id": 100021 }, "event_id": 249958648347009024, "event_type": "order_item.results_status_change", "timestamp": 1763661985 } ``` {% endtab %} {% tab title="Results Ready" %} ```json { "data": { "order_id": 249956252111773696, "order_item_id": 249956252111773699, "results_status": "results.results_ready", "test_taker": { "test_taker_id": "257837964552478720", "country_code": 1, "email": "john.doe@example.com", "first_name": "John", "last_name": "Doe", "phone_number": 4155551234 }, "variant_id": 100021 }, "event_id": 249958796259139584, "event_type": "order_item.results_status_change", "timestamp": 1763662021 } ``` {% endtab %} {% endtabs %} ### 5. Fetching results * When fetching results, a pre-signed URL will be returned which can be used to download test results * Use `order_item_id` and `test_taker_id` to fetch results {% tabs %} {% tab title="cURL" %} ```javascript curl --location --request GET \ 'https://vantage-sandbox.tryterra.co/api/v1/results/249956252111773699?test_taker_id=257837964552478720' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic ' ``` {% endtab %} {% tab title="Python" %} ```python import requests order_item_id = "249956252111773699" test_taker_id = "257837964552478720" url = f"https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}?test_taker_id={test_taker_id}" headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic ' } response = requests.get(url, headers=headers) print(response.text) print(response.status_code) ``` {% endtab %} {% tab title="GO" %} ```go package main import ( "fmt" "io" "net/http" ) func main() { orderItemID := "249956252111773699" testTakerID := "257837964552478720" url := fmt.Sprintf("https://vantage-sandbox.tryterra.co/api/v1/results/%s?test_taker_id=", orderItemID, testTakerID) client := &http.Client{} req, err := http.NewRequest("GET", url, nil) if err != nil { panic(err) } req.Header.Add("Content-Type", "application/json") req.Header.Add("Authorization", "Basic ") res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, err := io.ReadAll(res.Body) if err != nil { panic(err) } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="200" %} ```javascript { "download_url": "https://storage.googleapis.com/terra-diagnostics-results-sandbox-terra-diagnostics-sandbox/client/terra-client-payable/results/249717507/normalised.json?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=terra-diagnostics-sa%40terra-diagnostics-sandbox.iam.gserviceaccount.com%2F20251119%2Fauto%2Fstorage%2Fgoog4_request&X-Goog-Date=20251119T185304Z&X-Goog-Expires=899&X-Goog-Signature=c3d7b929233b6e08bd41d8f9959950736db897226b99014e2f10238185851f6fe2191d5c8e34a518a6325c21ff7c627a1a6753e5f3b4e52d219e3107be9c6feaa0362eb442a5766404bdab19bbb53c408584e15e68f00b1099dd71f6a82282ba3d970917562583a589aceca7d20599f4215874d3af9853661c6d31bc52407bdf59287415b162860b691e39fbf13f9e5a18768279cc8c318ea79383a6315ebaabec814f097a83c8102657a47d20f00c0dcac3152eb62f86c40190053824206bb21b27c01febf818a02aec1587de2770881f332c5e688d55f169ef61e7f15708963681a27665805863e313aa9fce39d3201177&X-Goog-SignedHeaders=host", "format": "json", "expires_at": "2025-11-19T19:08:04.40025031Z" } ``` {% endtab %} {% endtabs %} ### 6. Acknowledge Results * Once an end user sees their results, they are **required** to acknowledge it * How an end-user interfaces with the acknowledgement page must adhere to [Acknowledging Results](/vantage-api-docs/important-information/acknowledging-results.md) to be compliant * Importantly you need to inform us an end-user has acknowledged their results by hitting the following endpoint * We also use `order_item_id` and `test_taker_id` to acknowledge * ```hurl https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}/acknowledge?test_taker_id={test_taker_id} ``` {% tabs %} {% tab title="cURL" %} ```javascript curl --location --request POST \ 'https://vantage-sandbox.tryterra.co/api/v1/results/249956252111773699/acknowledge?test_taker_id=257837964552478720' \ --header 'Content-Type: application/json' \ --header 'Authorization: Basic ' ``` {% endtab %} {% tab title="Python" %} ```python import requests order_item_id = "249956252111773699" test_taker_id = "257837964552478720" url = f"https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}/acknowledge?test_taker_id={test_taker_id}" headers = { 'Content-Type': 'application/json', 'Authorization': 'Basic ' } response = requests.post(url, headers=headers) print(response.text) print(response.status_code) ``` {% endtab %} {% tab title="Go" %} ```go package main import ( "fmt" "io" "net/http" ) func main() { orderItemID := "249956252111773699" testTakerID := "257837964552478720" url := fmt.Sprintf("https://vantage-sandbox.tryterra.co/api/v1/results/%s/acknowledge?test_taker_id=%s", orderItemID, testTakerID) client := &http.Client{} req, err := http.NewRequest("POST", url, nil) if err != nil { panic(err) } req.Header.Add("Content-Type", "application/json") req.Header.Add("Authorization", "Basic ") res, err := client.Do(req) if err != nil { panic(err) } defer res.Body.Close() body, err := io.ReadAll(res.Body) if err != nil { panic(err) } fmt.Println(string(body)) } ``` {% endtab %} {% endtabs %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.tryterra.co/vantage-api-docs/getting-started/publish-your-docs.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.