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

> Paginated AI Receptionist inbox tasks for your organization, newest first: the call backs, refills and messages the receptionist (or staff) created for the front desk. Filter by `status`, `category`, title text or creation date. 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).

> [!NOTE]
>
> Rolling out: this endpoint is on staging first and not yet on `api.healos.ai`.

Inbox tasks are the call backs, refills and messages the AI Receptionist (or staff) leave for the front desk. They are returned newest first by `created_at`. Without `status`, every status is listed, archived tasks included; pass `status=todo` for the open ones.

`caller_phone` is the number of the call the task came from, so you can call back. It is `null` for a task with no linked phone call.

Task notes can contain protected health information. Store them as you would any patient record.

Guide: [Calls and inbox](https://docs.healos.ai/guides/receptionist/calls-and-inbox.md). Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /receptionist/tasks
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/tasks:
    get:
      tags:
        - Receptionist
      summary: List receptionist tasks
      description: >-
        Paginated AI Receptionist inbox tasks for your organization, newest
        first: the call backs, refills and messages the receptionist (or staff)
        created for the front desk. Filter by `status`, `category`, title text
        or creation date. 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
            enum:
              - todo
              - done
              - archived
              - all
            description: >-
              Only tasks with this status. `all` (the default) includes archived
              tasks.
            example: todo
          required: false
          name: status
          in: query
        - schema:
            type: string
            enum:
              - action
              - communicate
              - coordinate
              - document
              - order
              - call_followup
              - billing
              - insurance
              - refill
              - records
              - referral
              - appointment
            example: call_followup
          required: false
          name: category
          in: query
        - schema:
            type: string
            maxLength: 100
            description: Text to look for in the task title.
            example: refill
          required: false
          name: search
          in: query
        - schema:
            type: string
            description: Only tasks created at or after this instant (ISO 8601).
            example: '2026-10-27'
          required: false
          name: from_date
          in: query
        - schema:
            type: string
            description: Only tasks created at or before this instant (ISO 8601).
            example: '2026-10-28T23:59:59Z'
          required: false
          name: to_date
          in: query
      responses:
        '200':
          description: List of tasks
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReceptionistTaskListResponse'
        '400':
          description: >-
            Validation error: an unknown `status` or `category`, a date that is
            not ISO 8601, 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:
    ReceptionistTaskListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ReceptionistTask'
        meta:
          type: object
          properties:
            page:
              type: number
            limit:
              type: number
            total_pages:
              type: number
            total:
              type: number
              description: Tasks matching the filters across every page.
              example: 12
          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
    ReceptionistTask:
      type: object
      properties:
        id:
          type: string
          example: 7a5c0000-0000-4000-8000-000000000001
        title:
          type: string
        category:
          type: string
          nullable: true
        status:
          type: string
          example: todo
        source:
          type: string
          description: >-
            `manual` (created by staff or the API), `call` (created from a call)
            or `system`.
          example: call
        notes:
          type: string
          nullable: true
        due_date:
          type: string
          nullable: true
          example: '2026-10-30'
        patient_id:
          type: string
          nullable: true
        patient_label:
          type: string
          nullable: true
        assigned_provider_calendar_id:
          type: string
          nullable: true
        linked_call_id:
          type: string
          nullable: true
        caller_phone:
          type: string
          nullable: true
          description: >-
            The number the linked call came from, for a call back. Null without
            a phone call.
          example: '+15555550100'
        ehr_source:
          type: string
          nullable: true
          description: The EHR the organization had connected when the task was created.
        created_at:
          type: string
          example: '2026-10-27T14:07:50.000Z'
        updated_at:
          type: string
          example: '2026-10-27T14:08:02.000Z'
      required:
        - id
        - title
        - category
        - status
        - source
        - notes
        - due_date
        - patient_id
        - patient_label
        - assigned_provider_calendar_id
        - linked_call_id
        - caller_phone
        - ehr_source
        - 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.