Results

Read a questionnaire’s outcome: answers, score, transcript, and recording

The outcome of every call —both follow-up and triage— is read with the read endpoints.

Questionnaire (protocol run)

curl "https://{your-prod-endpoint}/v1/protocol-runs/{runId}" \
  -H "Authorization: Bearer oc_sk_..."

Returns the questionnaire with answers[], the calls with their transcription, a patient summary and the computed score. Protocol and version travel as summaries (protocol, protocol_version): for the questionnaire definition behind a question_key or an option_key, call GET /v1/protocols/{idOrKey}.

Relevant questionnaire fields:

Field	Description
questionnaire_status	pending, in_progress, completed, rejected, call_failed, wrong_number, no_answer, unresolved, cancelled.
score, score_class	The score and band the engine computed. They never change once computed.
effective_score_class, score_class_overridden	The classification in force: the most recent clinical override if there is one, otherwise the engine’s. Read this one for the current classification.
score_unavailable_reason	Why there is no score, when there is none.
sequence_number	Questionnaire number within the enrollment.
scheduled_at, started_at, ended_at	Timestamps.
reviewed_at, review_note	Clinical review, if any.

Answers

answers[] carries one entry per question the questionnaire reached, in the order the patient heard them. It is the same shape your webhooks receive.

{
  "question_key": "disnea",
  "question_text": "Have you had trouble breathing?",
  "type": "multiple_choice",
  "status": "answered",
  "asked_at": "2026-09-09T10:14:02Z",
  "answered_at": "2026-09-09T10:14:22Z",
  "call_id": "…",
  "value": ["mucha-dificultad"]
}

Field	Description
status	answered means it was answered; declined means it was put and the patient would not answer; asked means it was put and the call never captured an answer.
value	Typed by type: number, text, boolean, ISO date, or the option_keys picked on a multiple-choice question. null when there was no answer.
call_id	The attempt it happened on, so you can tie it to its transcription.

Questions and options travel by key (question_key, option_key), never by internal identifier: keys are stable across versions and do not change if someone rewrites the wording.

Call and transcript

curl "https://{your-prod-endpoint}/v1/calls/{callId}" \
  -H "Authorization: Bearer oc_sk_..."

Returns the call with its transcription: the conversation and only the conversation — who spoke, what they said and when. Relevant fields:

Field	Description
status	pending, dialing, in_progress, completed, failed, no_answer, cancelled, transferred.
call_direction	outbound (follow-up) or inbound (triage).
disconnect_reason	Why the call ended.
has_recording	Whether a recording is available.
started_at, ended_at, scheduled_at	Timestamps.

Recording

If has_recording is true, get a short-lived signed link:

curl "https://{your-prod-endpoint}/v1/calls/{callId}/recording" \
  -H "Authorization: Bearer oc_sk_..."

{ "data": { "url": "https://{your-prod-endpoint}/v1/calls/{callId}/recording/stream?expires=…&token=…" } }

That link redirects to the audio (audio/ogg); OlivIA reads the file from storage server-side, so your system never receives a storage credential. Returns 404 if there is no recording and 503 if storage is unavailable.