Digital Signing

In DELPHOS, signing a prescription is a status transition — not a separate cryptographic endpoint. The physician advances the prescription to the signed status by calling the status transition endpoint with the required fields.

Two-Phase Commit — From Stream to Signed

Voice-driven and chat-driven prescriptions in DELPHOS follow a two-phase commit pattern:

Phase 1 — Diagnostic preview (streaming). While the doctor dictates or types, the streaming prescription endpoint extracts items and runs the 6-gate advisory pipeline. The streamed result carries requires_confirmation: true — it is not persisted at this stage.
Phase 2 — Authoritative write. The doctor reviews the streamed preview in your UI, optionally tweaks dosages or removes items, then calls POST /v1/prescriptions to persist the prescription as a draft. The full lifecycle (draft → pending_review → validated → signed) and the post-persistence safety check then apply normally.

This separation lets the doctor see and adjust the prescription before committing — and ensures the post-persistence safety check (which does block signing on critical / contraindicated interactions) always runs against the final, doctor-approved item list rather than the raw streamed extraction.

Prerequisites for Signing

Before a prescription can be signed, all of the following must be true:

The prescription is in validated status.
All critical and contraindicated drug interactions have been acknowledged.
The signed_by UUID is provided in the request body.

If unacknowledged blocking interactions exist, the endpoint returns 409 with an unacknowledged_interactions error listing the interaction IDs and severities.

Signing a Prescription

PATCH /v1/prescriptions/{prescription_id}/status

Request body:

{
  "status": "signed",
  "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234"
}

Field	Type	Required	Description
`status`	string	Yes	Must be `"signed"`
`signed_by`	UUID	Yes	UUID of the doctor performing the signing

Responses:

Code	Meaning
`200`	Prescription signed — response contains updated `PrescriptionDetail`
`404`	Prescription not found
`409`	Unacknowledged interactions exist, or invalid status transition

curl
Python

curl -X PATCH "https://your-instance.delphos.app/v1/prescriptions/PRESCRIPTION_ID/status" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "signed", "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234"}'

import httpx

response = httpx.patch(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/status",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "status": "signed",
        "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234",
    },
)

if response.status_code == 409:
    error = response.json()
    if error.get("error") == "unacknowledged_interactions":
        print(f"Must acknowledge {error['interaction_count']} interactions first")
else:
    signed = response.json()
    print(f"Signed at: {signed['signed_at']}")

Handling Blocked Signing

If blocking interactions exist, the 409 response contains:

{
  "error": "unacknowledged_interactions",
  "prescription_id": "a7b8c9d0-...",
  "interaction_count": 2,
  "interactions": [
    {"id": "b1c2d3e4-...", "severity": "critical"},
    {"id": "c2d3e4f5-...", "severity": "contraindicated"}
  ],
  "message": "..."
}

Acknowledge each interaction (or all at once), then retry the sign transition:

import httpx

# Acknowledge all blocking interactions
httpx.post(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/interactions/acknowledge-all",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={"doctor_id": "e5f6a7b8-c9d0-1234-efab-345678901234"},
)

# Retry signing
response = httpx.patch(
    f"https://your-instance.delphos.app/v1/prescriptions/{prescription_id}/status",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "status": "signed",
        "signed_by": "e5f6a7b8-c9d0-1234-efab-345678901234",
    },
)

Signed Prescription Fields

After signing, the PrescriptionDetail response includes:

Field	Type	Description
`status`	string	`"signed"`
`signed_at`	datetime	Timestamp when the prescription was signed
`signed_by`	UUID	UUID of the doctor who signed

Full Signing Workflow

Ensure validated status — transition through draft → pending_review → validated, providing valid_until on the validation step.
Run safety check — POST /v1/prescriptions/{id}/safety-check to detect interactions.
Acknowledge blocking interactions — POST /v1/prescriptions/{id}/interactions/acknowledge-all or acknowledge individually.
Verify readiness — GET /v1/prescriptions/{id} and confirm can_sign: true.
Sign — PATCH /v1/prescriptions/{id}/status with {"status": "signed", "signed_by": "doctor-uuid"}.