> 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/important-information/acknowledging-results.md).

# Acknowledging Results

## 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.

{% hint style="danger" %}
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.
{% endhint %}

{% hint style="warning" %}
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.
{% endhint %}

## 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.

<figure><img src="/files/WmZP3NByZBbhNmtFgJAg" alt="Example acknowledgement page shown to the end user"><figcaption></figcaption></figure>

## 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`.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```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)
```

{% endtab %}

{% tab title="Go" %}

```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))
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="200" %}

```json
{ "status": "acknowledged" }
```

{% endtab %}
{% endtabs %}

To find results that are ready but not yet acknowledged, list `GET /api/v1/results` and filter on `is_acknowledged: false` - see [Managing orders](/vantage-api-docs/documentation/managing-orders.md#list-results).