Acknowledge a flag

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "on_behalf_of": {
    "npi": "1234567893",
    "name": "Dr. Alex Morgan, NP"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({on_behalf_of: {npi: '1234567893', name: 'Dr. Alex Morgan, NP'}})
};

fetch('https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge"

payload = { "on_behalf_of": {
        "npi": "1234567893",
        "name": "Dr. Alex Morgan, NP"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "0190f5d8-4b2c-7d5e-9f10-b1c2d3e4f5a6",
  "status": "acknowledged",
  "severity": "critical",
  "title": "Acute GI distress",
  "rule_code": "acute_gi",
  "source": "alert_rule",
  "enrollment_id": "0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5",
  "external_patient_id": "brand-pt-48213",
  "plan_code": "ai_only",
  "risk_level": "high",
  "raised_risk_to": "high",
  "details": {
    "symptom": "vomiting",
    "severity_score": 4,
    "escalation_reason": null,
    "values": {}
  },
  "triggering_records": [
    {
      "type": "symptom_log",
      "id": "0190f5c9-7f80-7192-8cb4-3d4e5f607182",
      "occurred_at": "2026-10-26T13:50:00Z"
    }
  ],
  "timeline": [],
  "treatment": null,
  "coach_note": null,
  "ack_due_at": "2026-10-26T16:05:00Z",
  "redelivery_count": 0,
  "acknowledgement": {
    "at": "2026-10-26T14:20:00Z",
    "by": {
      "npi": "1234567893",
      "name": "Dr. Alex Morgan, NP"
    }
  },
  "resolution": null,
  "created_at": "2026-10-26T14:05:00Z",
  "updated_at": "2026-10-26T14:20:00Z"
}

POST

clinical-flags

{flag_id}

acknowledge

Acknowledge a flag

curl --request POST \
  --url https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "on_behalf_of": {
    "npi": "1234567893",
    "name": "Dr. Alex Morgan, NP"
  }
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({on_behalf_of: {npi: '1234567893', name: 'Dr. Alex Morgan, NP'}})
};

fetch('https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://sandbox.rx.tera.health/v1/clinical-flags/{flag_id}/acknowledge"

payload = { "on_behalf_of": {
        "npi": "1234567893",
        "name": "Dr. Alex Morgan, NP"
    } }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "0190f5d8-4b2c-7d5e-9f10-b1c2d3e4f5a6",
  "status": "acknowledged",
  "severity": "critical",
  "title": "Acute GI distress",
  "rule_code": "acute_gi",
  "source": "alert_rule",
  "enrollment_id": "0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5",
  "external_patient_id": "brand-pt-48213",
  "plan_code": "ai_only",
  "risk_level": "high",
  "raised_risk_to": "high",
  "details": {
    "symptom": "vomiting",
    "severity_score": 4,
    "escalation_reason": null,
    "values": {}
  },
  "triggering_records": [
    {
      "type": "symptom_log",
      "id": "0190f5c9-7f80-7192-8cb4-3d4e5f607182",
      "occurred_at": "2026-10-26T13:50:00Z"
    }
  ],
  "timeline": [],
  "treatment": null,
  "coach_note": null,
  "ack_due_at": "2026-10-26T16:05:00Z",
  "redelivery_count": 0,
  "acknowledgement": {
    "at": "2026-10-26T14:20:00Z",
    "by": {
      "npi": "1234567893",
      "name": "Dr. Alex Morgan, NP"
    }
  },
  "resolution": null,
  "created_at": "2026-10-26T14:05:00Z",
  "updated_at": "2026-10-26T14:20:00Z"
}

Authorizations

Authorization

string

header

default:Bearer sandbox_any_token_works

required

The brand's prescriber system (its clinician tool or Beluga), with its own OAuth client separate from the brand server's. Every write carries the individual prescriber in on_behalf_of. Tokens last 1 hour.

Headers

Idempotency-Key

string

Optional on this action. When sent, it works as on creating requests (24 hours, same body).

Required string length: 8 - 255

Path Parameters

flag_id

string<uuid>

required

Body

application/json

on_behalf_of

object

required

The individual prescriber acting through a clinical client. name and at least one of npi or prescriber_id are required. Stored on the flag with the client that sent it (alerts.*_by_prescriber).

Option 1
Option 2

Show child attributes

Response

The acknowledged flag.

string<uuid>

required

Example:

"0190f5d8-4b2c-7d5e-9f10-b1c2d3e4f5a6"

status

enum<string>

required

open until a prescriber acknowledges it; acknowledged until resolved. dismissed flags were closed by TeraRx as raised in error and never change risk.

Available options:

open,

acknowledged,

resolved,

dismissed

Example:

"open"

severity

enum<string>

required

Available options:

info,

warning,

critical

Example:

"critical"

title

string

required

Example:

"Acute GI distress"

source

enum<string>

required

An alert rule on the logs, the AI Coach escalating a conversation (ai_only), or a coach.

Available options:

alert_rule,

ai_coach_escalation,

coach

Example:

"alert_rule"

enrollment_id

string<uuid>

required

Example:

"0190f5c2-3a1b-7c4d-8e9f-a0b1c2d3e4f5"

external_patient_id

string

required

The brand's patient id, to find the patient in your own system.

Required string length: 1 - 128

Pattern: ^[\x21-\x7E]+$

Example:

"brand-pt-48213"

plan_code

enum<string>

required

ai_only: the AI Coach only. Escalations go to the brand's prescriber as clinical flags.
ai_health_fitness: the AI Coach plus a health coach (nutrition) and a fitness coach.

Available options:

ai_only,

ai_health_fitness

Example:

"ai_health_fitness"

risk_level

enum<string>

required

The enrollment's risk level now.

Available options:

normal,

elevated,

high

Example:

"normal"

details

object

required

What triggered the flag.

Show child attributes

triggering_records

object[]

required

Show child attributes

timeline

object[]

required

Show child attributes

redelivery_count

integer

required

How many times the flag has been re-delivered for a missed ack_due_at.

Example:

0

created_at

string<date-time>

required

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

rule_code

string | null

The alert rule that raised it, for example acute_gi, red_flag_symptom, moderate_side_effects.

Example:

"acute_gi"

raised_risk_to

enum<string> | null

The level this flag raised the enrollment to.

Available options:

normal,

elevated,

high,

null

Example:

"high"

treatment

object | null

The treatment when the flag was raised.

Show child attributes

coach_note

string | null

The coach's note, on the coached plan.

Example:

null

ack_due_at

string<date-time> | null

Acknowledge before this time, set from the brand's agreed acknowledgement time. If it passes, clinical.flag_redelivered is sent.

Example:

"2026-10-26T16:05:00Z"

acknowledgement

object | null

Show child attributes

resolution

object | null

Show child attributes

updated_at

string<date-time>

ISO 8601 in UTC.

Example:

"2026-10-26T14:05:00Z"

Auth

Tenants

Enrollments

Treatment

Consent

Brand logs

Events

Reports

Data requests

Patient

Forms

Logging

Progress

Protocols and plans

Meal swap

Library

Care messaging

Feedback

AI Coach

Reminders

Clinical flags

Webhooks

Acknowledge a flag

Authorizations

Headers

Path Parameters

Body

Response