> ## Documentation Index
> Fetch the complete documentation index at: https://docs.healos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Receptionist call transcripts

> Pull every AI Receptionist call, with its transcript and extracted details, into your own system

Use this to build your own alerts, task rules or summaries from what the AI
receptionist heard, or to keep a copy of every call next to the patient's
record in your system.

| | |
| - | - |
| **Scope** | `receptionist:read` |
| **Cost** | Free |
| **Outside systems** | None for the list and the call. The recording is read from HealOS storage or the voice provider. |
| **Safety** | Read-only and safe to retry. Downloads are written to your recording access log. |

## What you get

Three read-only endpoints:

| Endpoint | Returns |
| - | - |
| [`GET /receptionist/calls`](https://docs.healos.ai/api-reference/receptionist/list-receptionist-calls) | Calls newest first: status, outcome, caller, duration, summary, whether a recording and transcript exist |
| [`GET /receptionist/calls/{callId}`](https://docs.healos.ai/api-reference/receptionist/get-a-receptionist-call) | The call plus the full transcript and the extracted details |
| [`GET /receptionist/calls/{callId}/recording`](https://docs.healos.ai/api-reference/receptionist/download-a-call-recording) | The audio |

The dashboard's summary is two to three sentences and a follow-up task is only
created when the AI judges the call needs one. The transcript and
`extracted_data` are the raw material behind both, so your own rules can be as
detailed as you like.

## Poll for new calls

Page through calls received since your last run. `from_date` and `to_date`
filter on `created_at`, the time HealOS received the call record, so keep the
latest `created_at` you have seen and ask for everything after it.

```bash theme={null}
curl -sS "https://api.healos.ai/ext-api/v1/receptionist/calls?from_date=2026-10-27T00:00:00Z&limit=100" \
  -H "X-API-Key: $HEALOS_API_KEY"
```

```json theme={null}
{
  "data": [
    {
      "id": "c0a80101-0000-4000-8000-000000000001",
      "direction": "inbound",
      "status": "completed",
      "outcome": "message_taken",
      "outcome_reason": null,
      "transfer_status": null,
      "caller_name": "Pat Example",
      "from_number": "+15555550100",
      "to_number": "+15555550199",
      "patient_id": "700000000000000001",
      "started_at": "2026-10-27T14:03:11.000Z",
      "ended_at": "2026-10-27T14:07:42.000Z",
      "duration_sec": 271,
      "summary": "Caller asked to reschedule a follow-up; no Tuesday slot was open, so a callback was requested.",
      "has_recording": true,
      "has_transcript": true,
      "review_status": "unreviewed",
      "created_at": "2026-10-27T14:07:50.000Z",
      "updated_at": "2026-10-27T14:08:02.000Z"
    }
  ],
  "meta": { "page": 1, "limit": 100, "total": 1, "total_pages": 1 }
}
```

A call's `summary`, `outcome` and `extracted_data` are filled in by the
post-call analysis, which runs within a minute of the call ending; until then
they are `null`. Fetch such a call again later, or use the webhook below as the
trigger.

## Or react to the post-call webhook

In the dashboard, under **AI Receptionist → Settings → Automations**, turn on
the post-call webhook and give it your URL. Within seconds of each call ending
HealOS sends the call's `call_id`, outcome, summary and caller number. The
webhook does not carry the transcript: use `call_id` to fetch it.

```bash theme={null}
curl -sS "https://api.healos.ai/ext-api/v1/receptionist/calls/$CALL_ID" \
  -H "X-API-Key: $HEALOS_API_KEY"
```

```json theme={null}
{
  "data": {
    "id": "c0a80101-0000-4000-8000-000000000001",
    "summary": "Caller asked to reschedule a follow-up; no Tuesday slot was open, so a callback was requested.",
    "transcript": [
      { "speaker": "assistant", "message": "Thank you for calling. How can I help?" },
      { "speaker": "user", "message": "I need to move my follow-up with Dr. Example." }
    ],
    "extracted_data": {
      "reason_for_call": "reschedule follow-up",
      "callback_requested": true,
      "appointment_requested": false
    }
  }
}
```

(Other fields omitted. `speaker` is `user` for the caller and `assistant` for
the AI receptionist.)

## Download the recording

```bash theme={null}
curl -sS "https://api.healos.ai/ext-api/v1/receptionist/calls/$CALL_ID/recording" \
  -H "X-API-Key: $HEALOS_API_KEY" \
  -o "call-$CALL_ID.mp3"
```

The body is the audio, usually `audio/mpeg`. Each download is written to your
organization's recording access log, the same as a download from the dashboard.

## From the CLI

```bash theme={null}
healos receptionist calls list --from 2026-10-27 --outcome message_taken,could_not_book
healos receptionist calls transcript c0a80101-0000-4000-8000-000000000001
healos receptionist calls recording c0a80101-0000-4000-8000-000000000001 --out call.mp3
```

## Keep in mind

* Transcripts, summaries and recordings are protected health information.
  Store and transmit them as you would any patient record.
* `patient_id` is set when the receptionist matched the caller to a chart;
  use it with [`GET /patients/{patientId}`](https://docs.healos.ai/api-reference/patients/get-patient-by-id).
* `outcome` values: `booked`, `rescheduled`, `cancelled`, `confirmed`, `could_not_book`,
  `transferred`, `question_answered`, `message_taken`, `hung_up`, `other`.
  Filter the list with `outcome=message_taken,could_not_book` to find calls
  that need a human.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.