Future Technologies Company

Clinical Scribe API

Submit a consultation recording, poll until it is ready, and receive a structured clinical note for your record system. This page is the reference; every other path on this host returns JSON.

How it works

Your system posts a recording and gets an identifier back in under a second. Transcription and note generation happen in the background, so nothing waits on a long request. You poll the identifier until the note is ready, typically within about thirty-five seconds.

The answer comes back in two halves that cannot be confused with each other. note is what belongs in the patient record. advisory is what a clinician reads before signing: warnings, drug register verdicts, and the transcript.

Authentication

Every request carries the API key FTC issued you, in either header:

Authorization: Bearer ftcs_a1b2c3d4_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
X-API-Key: ftcs_a1b2c3d4_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Keys are 46 characters: a fixed ftcs label, an 8-character identifier, and a 32-character secret. The identifier is safe to log and is how we tell your keys apart. The secret is shown once, when the key is issued, and is stored only as a hash, so we cannot recover it for you. If a key is lost, ask for a new one and the old one is revoked.

Every rejection returns the same 401 with the same body, whether the key is unknown, wrong, revoked, or belongs to a suspended account. That is deliberate, so the response cannot be used to work out which keys exist.

Submit a recording

Send multipart/form-data:

Retrying safely

Send an Idempotency-Key header. If you repeat a request with the same key, you get the original submission back rather than a second consultation. Keys are scoped to your account, so they cannot collide with another hospital's.

Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7

Response

202 Accepted, with a Location header pointing at the poll URL.

{
  "id": "0b7f3d5a-9c21-4a8e-b4f1-3d2c9a8e7f06",
  "status": "queued",
  "stage": "received",
  "percent": 0
}

Collect the note

Poll every few seconds. note and advisory are empty objects until status becomes ready.

When a submission fails

The poll still returns 200, with status: "failed" and an error object carrying code, message and retryable. Retry only when retryable is true.

The note

Eleven fields, named to match the Patient Episode form. A field the consultation did not cover may be absent or present and null, so treat the two the same. The one exception is allergies: in the note this API returns it is always present and never null. What a clinician later signs in your own system is theirs to edit.

Each entry in the two medication lists:

{
  "name_as_said": "Metformin",
  "dose": "500 mg",
  "route": "oral",
  "frequency": "twice daily",
  "duration": "for 3 months",
  "evidence_segments": [14, 15]
}

name_as_said is the drug exactly as the clinician named it, before any register lookup. evidence_segments point at the numbered transcript in advisory.segments, so any entry can be checked against what was said.

The advisory half

Warnings

Three severities, and they describe how likely something is to be a mistake:

Each warning carries a stable code for counting and testing, a message for a clinician to read, a detail explaining it, and evidence_segments pointing at the transcript so any warning can be checked against what was actually said.

Drug register verdicts

The drugs listed in the note's current medications and new prescriptions (or, only when both are empty, in its free-text medication field) are checked by our own code against the Saudi register, never by a language model. A drug mentioned elsewhere in the note is not checked. Three outcomes:

Errors

Every non-2xx response uses one shape:

{
  "error": {
    "code": "not_found",
    "message": "No such encounter.",
    "request_id": "d719bfc0adbe"
  }
}

Quote request_id when you contact us. It is how we find your exact request in our logs.

Validation failures return 400, not 422. A 404 is returned for an encounter belonging to another account exactly as for one that does not exist, so the API cannot be used to discover whether an identifier is real.

A complete exchange

curl -X POST https://api.ftech.sa/v1/encounters \
  -H "Authorization: Bearer $FTC_API_KEY" \
  -H "Idempotency-Key: 7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -F "audio=@consultation.m4a" \
  -F "mrn=1140027" \
  -F "patient_sex=Female" \
  -F "patient_age=52"

# 202 Accepted
# {"id":"0b7f3d5a-...","status":"queued","stage":"received","percent":0}

curl https://api.ftech.sa/v1/encounters/0b7f3d5a-... \
  -H "Authorization: Bearer $FTC_API_KEY"

# 200 OK, once status is "ready"
# {"status":"ready","stage":"ready","percent":100,
#  "note":{...},"advisory":{...}}