# 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](https://docs.tryterra.co/vantage-api-docs/getting-started/ordering-your-first-test) 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](https://docs.tryterra.co/vantage-api-docs/important-information/acknowledging-results "mention") 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 %}