> ## 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.

# List receptionist calls

> Paginated AI Receptionist calls for your organization, newest first, with each call's status, outcome, summary and whether a recording and transcript exist. Filter by date received (`from_date`, `to_date`), outcome, or a caller name or number. Transcripts and extracted details are on GET /receptionist/calls/{callId}. Requires the receptionist:read scope.

| Requirement | Detail |
| - | - |
| **Scope** | `receptionist:read` |
| **Rate limit** | About 60 requests per minute per API key (shared by all endpoints; approximate) |
| **Cost** | Free |

> [!TIP]
>
> **Safety**
>
> * **Writes data:** No
> * **Safe to retry:** Yes
> * **Contacts an outside system:** None
> * **Dry run:** Not needed (read-only).

Calls are returned newest first by the time HealOS received the call record (`created_at`), which is what `from_date` and `to_date` filter on. Each item carries the status, outcome and post-call summary; the transcript and extracted details are on [Get a receptionist call](https://docs.healos.ai/api-reference/receptionist/get-a-receptionist-call.md), and the audio on [Download a call recording](https://docs.healos.ai/api-reference/receptionist/download-a-call-recording.md).

The `id` is the same `call_id` the post-call webhook sends, so you can use the webhook as the trigger and this endpoint to fetch the rest.

Guide: [Receptionist call transcripts](https://docs.healos.ai/recipes/receptionist-call-transcripts.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /receptionist/calls
openapi: 3.0.0
info:
  title: Healos External API
  version: 1.0.0
  description: >-
    External API for managing patients, documents, and appointments, listing
    providers and note templates, pulling clinical notes (with transcript and
    patient context), running insurance eligibility checks, browsing the EHR
    action catalog, reading AI Receptionist calls (summary, transcript,
    extracted details and recording), managing the AI Receptionist inbox tasks,
    and registering webhooks for note and document events.
servers:
  - url: https://api.healos.ai/ext-api/v1
    description: Production
  - url: http://localhost:8787/ext-api/v1
    description: Local development
security:
  - ApiKeyAuth: []
paths:
  /receptionist/calls:
    get:
      tags:
        - Receptionist
      summary: List receptionist calls
      description: >-
        Paginated AI Receptionist calls for your organization, newest first,
        with each call's status, outcome, summary and whether a recording and
        transcript exist. Filter by date received (`from_date`, `to_date`),
        outcome, or a caller name or number. Transcripts and extracted details
        are on GET /receptionist/calls/{callId}. Requires the receptionist:read
        scope.
      parameters:
        - schema:
            type: string
            pattern: ^\d+$
            default: '1'
            description: Page number, from 1.
            example: '1'
          required: false
          name: page
          in: query
        - schema:
            type: string
            pattern: ^\d+$
            default: '20'
            description: >-
              Results per page, 1-100 (default 20). Larger values are treated as
              100.
            example: '20'
          required: false
          name: limit
          in: query
        - schema:
            type: string
            description: >-
              Only calls received at or after this instant (ISO 8601). A date
              without a time means the start of that day in UTC.
            example: '2026-10-27'
          required: false
          name: from_date
          in: query
        - schema:
            type: string
            description: >-
              Only calls received at or before this instant (ISO 8601). A date
              without a time means the start of that day in UTC, so use the next
              day or add a time to include a whole day.
            example: '2026-10-28T23:59:59Z'
          required: false
          name: to_date
          in: query
        - schema:
            type: string
            description: >-
              Comma-separated call outcomes to include. One or more of: booked,
              rescheduled, cancelled, could_not_book, transferred,
              transferred_connected, transferred_not_answered,
              transferred_unknown, question_answered, message_taken, hung_up,
              other, not_recorded. An unknown value is a 400.
            example: message_taken,could_not_book
          required: false
          name: outcome
          in: query
        - schema:
            type: string
            maxLength: 100
            description: Caller name or phone number to search for.
            example: 555-0100
          required: false
          name: search
          in: query
      responses:
        '200':
          description: List of calls
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceptionistCallListResponse'
        '400':
          description: >-
            Validation error: a date that is not ISO 8601, an unknown `outcome`,
            or a non-numeric `page`/`limit`
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs receptionist:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    ReceptionistCallListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReceptionistCall'
        meta:
          type: object
          properties:
            page:
              type: number
            limit:
              type: number
            total_pages:
              type: number
            total:
              type: number
              description: Calls matching the filters across every page.
              example: 42
          required:
            - page
            - limit
            - total_pages
            - total
      required:
        - data
        - meta
    ValidationError:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
      required:
        - error
    Error:
      type: object
      properties:
        error:
          type: string
      required:
        - error
    RateLimitError:
      type: object
      properties:
        error:
          type: string
          example: Rate limit exceeded. Please retry after the window resets.
        code:
          type: string
          enum:
            - daily_cap_reached
          description: >-
            Set when the organization reached its daily cap for this paid
            operation (not on a per-minute limit).
        reset_at:
          type: string
          format: date-time
          description: 'With `code`: when the daily cap resets (next 00:00 UTC).'
          example: '2026-10-28T00:00:00.000Z'
      required:
        - error
    ReceptionistCall:
      type: object
      properties:
        id:
          type: string
          description: >-
            Call identifier. The same id the post-call webhook sends as
            `call_id`.
          example: c0a80101-0000-4000-8000-000000000001
        direction:
          type: string
          description: '`inbound` or `outbound`.'
          example: inbound
        status:
          type: string
          description: >-
            The call status as the dashboard shows it: completed, missed,
            voicemail or failed.
          example: completed
        outcome:
          type: string
          nullable: true
          description: >-
            What the call ended as: booked, rescheduled, cancelled, confirmed,
            could_not_book, transferred, question_answered, message_taken,
            hung_up, other. Null until the post-call analysis has run.
          example: message_taken
        outcome_reason:
          type: string
          nullable: true
          description: >-
            Why the call was transferred or could not be booked
            (asked_for_person, no_availability, chart_not_found,
            insurance_not_accepted, ...).
          example: no_availability
        transfer_status:
          type: string
          nullable: true
          description: >-
            How a warm transfer ended (connected, no_answer, busy, voicemail,
            ...). Null when no transfer was attempted.
          example: connected
        caller_name:
          type: string
          nullable: true
          example: Pat Example
        from_number:
          type: string
          description: The caller's number (E.164).
          example: '+15555550100'
        to_number:
          type: string
          description: The receptionist line that was called (E.164).
          example: '+15555550199'
        patient_id:
          type: string
          nullable: true
          description: >-
            The HealOS patient the call was linked to, usable with GET
            /patients/{patientId}. Null when the caller was not matched to a
            chart.
          example: '700000000000000001'
        started_at:
          type: string
          nullable: true
          example: '2026-10-27T14:03:11.000Z'
        ended_at:
          type: string
          nullable: true
          example: '2026-10-27T14:07:42.000Z'
        duration_sec:
          type: integer
          nullable: true
          description: Call length in seconds, which is also the recording length.
          example: 271
        summary:
          type: string
          nullable: true
          description: The post-call summary (two to three sentences).
          example: >-
            Caller asked to reschedule a follow-up with Dr. Example; no Tuesday
            slot was open, so a callback was requested.
        has_recording:
          type: boolean
          description: >-
            Whether a recording exists. Fetch the audio with GET
            /receptionist/calls/{callId}/recording.
        has_transcript:
          type: boolean
          description: >-
            Whether a transcript exists. GET /receptionist/calls/{callId}
            returns it.
        review_status:
          type: string
          description: 'Staff review state in the HealOS inbox: unreviewed or reviewed.'
          example: unreviewed
        created_at:
          type: string
          description: >-
            When HealOS received the call record. `from_date` and `to_date`
            filter on this.
          example: '2026-10-27T14:07:50.000Z'
        updated_at:
          type: string
          example: '2026-10-27T14:08:02.000Z'
      required:
        - id
        - direction
        - status
        - outcome
        - outcome_reason
        - transfer_status
        - caller_name
        - from_number
        - to_number
        - patient_id
        - started_at
        - ended_at
        - duration_sec
        - summary
        - has_recording
        - has_transcript
        - review_status
        - created_at
        - updated_at
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from /api/v1/ext-api-keys

````

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