Acknowledging Results

Result acknowledgment is a mandatory compliance step: patients cannot access their results until you acknowledge them, and failing to acknowledge transfers liability to your organisation.

Overview

Acknowledging results is not optional - it is a fundamental requirement in the patient care workflow. This acknowledgment serves as documentation that clients have reviewed test outcomes and take responsibility for communicating appropriate severity levels to their end users.

All results, whether indicating low to high clinical escalation, must be explicitly acknowledged within the system before patients can access their results. This mandatory acknowledgment protects patients by ensuring they receive informed guidance about their test outcomes and any necessary next steps.

Failure to acknowledge results initiates a chain of liability that transfers responsibility directly to you, and your organisation assumes full liability for any adverse outcomes resulting from delayed or unacknowledged results.

If results remain unacknowledged, test suppliers and medical teams are authorised to reach out directly to patients to ensure they receive critical health information. Escalated results carry an explicit acknowledgment_due_by deadline in the webhook payload.

Acknowledgment must be an explicit user action

The acknowledge call records the end user's affirmative confirmation that they have received and viewed their results. It must be triggered by an explicit end-user action - a button or checkbox in your UI after the results are displayed - never automatically by your backend on retrieval or delivery. Build the flow as: fetch the result → present it to the user → the user confirms → your backend calls the acknowledge endpoint.

Example acknowledgement page

• N.B. The test taker cannot see results until acknowledging.

Acknowledgement endpoint

POST /api/v1/results/{order_item_id}/acknowledge?test_taker_id={test_taker_id}

Both order_item_id (path) and test_taker_id (query) are required. The test_taker_id arrives on every result webhook, or via GET /api/v1/orders/{orderID} under items[].test_taker_ids.

cURL

curl --request POST \
  'https://vantage-sandbox.tryterra.co/api/v1/results/251285377984405507/acknowledge?test_taker_id=257837964552478720' \
  -u 'YOUR_DEV_ID:YOUR_API_KEY'

Python

import requests

order_item_id = "251285377984405507"
test_taker_id = "257837964552478720"
url = f"https://vantage-sandbox.tryterra.co/api/v1/results/{order_item_id}/acknowledge"

response = requests.post(
    url,
    auth=("YOUR_DEV_ID", "YOUR_API_KEY"),
    params={"test_taker_id": test_taker_id},
)
print(response.json())
print(response.status_code)

Go

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	orderItemID := "251285377984405507"
	testTakerID := "257837964552478720"
	url := fmt.Sprintf(
		"https://vantage-sandbox.tryterra.co/api/v1/results/%s/acknowledge?test_taker_id=%s",
		orderItemID, testTakerID,
	)

	req, err := http.NewRequest("POST", url, nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth("YOUR_DEV_ID", "YOUR_API_KEY")

	res, err := http.DefaultClient.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))
}

200

{ "status": "acknowledged" }

To find results that are ready but not yet acknowledged, list GET /api/v1/results and filter on is_acknowledged: false - see Managing orders.