Clinical Decision Support

Corrective CDSS (“clinical decision support”) reviews a completed consultation against clinical guidelines and flags actionable issues in the record — an omitted medication, an incorrect dosage, a non-pertinent order. Each finding is an alert. Alerts are attached to the medical record: read them from the cdssAlerts field on the medical record documents endpoint. cdssAlerts is null when clinical decision support is disabled for the session or no alerts were generated, and [] when it ran and produced none.

The alert model

{
  "id": "cfa_9cba9fa0…SKULL_XRAY",
  "elementId": "SKULL_XRAY",
  "reason": "Loss of consciousness after a suspected concussion; a skull X-ray does not adequately assess intracranial injury.",
  "action": "Replace the skull X-ray with a non-contrast head CT.",
  "actionCategory": "replace",
  "type": "diagnostic_test",
  "issue": "not_pertinent",
  "element": "Skull X-ray",
  "severity": "red",
  "source": ["NICE Head Injury: Assessment and Early Management Guideline NG232, 2023"],
  "newPlanElement": {
    "type": "diagnostic_test",
    "element": "Non-contrast head CT",
    "id": "HEAD_CT",
    "content": "Non-contrast head CT",
    "laboratory": null
  },
  "previousTestDate": null,
  "guidelineIntervalDays": null,
  "status": "accepted"
}

Use id as the alert’s identifier — it is a stable, opaque token. elementId is the clinical element key (e.g. ASPIRIN); it is human-readable but can repeat across documents, so never use it as an identifier.

Field reference

Field	Type	Description
`id`	string	Stable, opaque alert identifier. Use it as-is; do not parse it
`elementId`	string	Clinical element key (e.g. `ASPIRIN`). Human-readable, not unique across documents
`reason`	string	Why the alert was raised
`action`	string	The recommended action
`actionCategory`	string	`add` \| `remove` \| `replace` \| `modify`
`type`	string	Order type: `medication`, `diagnostic_test`, `interconsultation`, `referral`, `follow_up`, `general_order`, `non_pharmacological`, `warning_signs`
`issue`	string	`incorrect_dosage` \| `omission` \| `not_pertinent`
`element`	string	The plan element the alert refers to
`severity`	string	`red` \| `orange` \| `yellow`
`source`	array	Guideline citations backing the alert
`newPlanElement`	object \| null	The element the alert proposes (on `add`/`replace`/`modify`): `{ type, element, id, content, laboratory }`. Its `content` shape varies with the record’s template
`previousTestDate`	string \| null	For test recommendations, the date of the previous test
`guidelineIntervalDays`	number \| null	For test recommendations, the guideline interval in days
`status`	string	The doctor’s decision: `pending` \| `accepted` \| `rejected`

Acting on an alert

Record the doctor’s decision with the alert’s id. Accepting an alert applies its proposed change to the medical record; rejecting one leaves the record unchanged. Both require an API key carrying scribe:write or scribe:cdss.

curl -X POST https://scribe-api.telepatia.ai/v1/cdss/alerts/ALERT_ID/accept \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO",
  "elementId": "IBUPROFEN",
  "status": "accepted"
}

Use the same request against /reject to reject the alert.

A success response means the decision was recorded. An accepted alert is applied to the medical record in the background, so re-reading the record immediately afterwards may still show its previous content. The alert’s own status is updated right away.

Recording the same decision twice is safe — the decision is stored per alert, so a retry produces the same result.

Several alerts at once

Send one request per consultation review instead of one per alert. Every alert is validated before any decision is recorded, so a batch containing an alert you cannot act on records nothing.

curl -X POST https://scribe-api.telepatia.ai/v1/cdss/decisions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decisions":[{"id":"ALERT_ID","decision":"accepted"}]}'

Response:

{
  "decisions": [
    {
      "id": "cfa_bXJkLWFiYy0xMjMfSUJVUFJPRkVO",
      "elementId": "IBUPROFEN",
      "status": "accepted"
    }
  ]
}

Each decision is accepted or rejected. The response lists one entry per submitted alert, in the order received. An alert may appear only once per request.

Errors

Status	Code	When
400	`parameter_invalid`	`alertId` is not a valid alert identifier, or the batch repeats an alert
403	`permission_denied`	the API key lacks `scribe:write` and `scribe:cdss`
404	`resource_not_found`	the alert does not exist or is not available for this API key
409	`resource_not_active`	clinical decision support is not active for the consultation

Getting Started

Consultations

Scribe Sessions

Webhooks

Smart Templates

Session Templates

Accounts

Patients

Reference

Clinical Decision Support

The alert model

Field reference

Acting on an alert

Several alerts at once

Errors

​The alert model

​Field reference

​Acting on an alert

​Several alerts at once

​Errors

The alert model

Field reference

Acting on an alert

Several alerts at once

Errors