> ## 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 received faxes

> Faxes your organization received (and documents filed into the fax inbox), newest first. Summary fields only: GET /faxes/{faxId} has the extracted fields. Requires the fax:read scope.

| Requirement | Detail |
| - | - |
| **Scope** | `fax:read` (rolling out: not yet on `api.healos.ai`) |
| **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).

Errors: [Error catalog](https://docs.healos.ai/errors.md).


## OpenAPI

````yaml openapi/ext-api-v1.json GET /faxes
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:
  /faxes:
    get:
      tags:
        - Fax
      summary: List received faxes
      description: >-
        Faxes your organization received (and documents filed into the fax
        inbox), newest first. Summary fields only: GET /faxes/{faxId} has the
        extracted fields. Requires the fax: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:
              - prescription
              - lab_result
              - referral
              - medical_record
              - records_request
              - insurance
              - prior_auth
              - other
            description: Only faxes classified as this type.
          required: false
          name: document_type
          in: query
        - schema:
            type: string
            pattern: ^\d{1,19}$
            description: Only faxes linked to this HealOS patient.
          required: false
          name: patient_id
          in: query
      responses:
        '200':
          description: Received faxes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FaxListResponse'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient scope (needs fax:read)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitError'
components:
  schemas:
    FaxListResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/FaxSummary'
        meta:
          type: object
          properties:
            page:
              type: number
            limit:
              type: number
            total_pages:
              type: number
          required:
            - page
            - limit
            - total_pages
      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
    FaxSummary:
      type: object
      properties:
        id:
          type: string
          example: f0000000-0000-4000-8000-000000000001
        received_at:
          type: string
          example: '2026-11-05T15:00:00.000Z'
        source:
          type: string
          nullable: true
          description: '`ifax`, `email`, `upload`, `elation` or `weave`.'
          example: ifax
        from_number:
          type: string
          nullable: true
          example: '+15555550123'
        filename:
          type: string
        file_type:
          type: string
          example: pdf
        pages:
          type: integer
        document_type:
          type: string
          enum:
            - prescription
            - lab_result
            - referral
            - medical_record
            - records_request
            - insurance
            - prior_auth
            - other
        is_urgent:
          type: boolean
        processing_status:
          type: string
          description: >-
            Text and field extraction: `pending`, `processing`, `completed` or
            `failed`.
          example: completed
        patient_id:
          type: string
          nullable: true
          description: The HealOS patient the fax is linked to, if any.
        ehr_filing:
          $ref: '#/components/schemas/FaxEhrFiling'
      required:
        - id
        - received_at
        - source
        - from_number
        - filename
        - file_type
        - pages
        - document_type
        - is_urgent
        - processing_status
        - patient_id
        - ehr_filing
    FaxEhrFiling:
      type: object
      properties:
        status:
          type: string
          description: >-
            Filing to the connected EHR: `pending`, `syncing`, `synced`,
            `needs_review`, `failed` or `skipped`.
          example: synced
        ehr:
          type: string
          nullable: true
          example: modmed
        ehr_patient_id:
          type: string
          nullable: true
        ehr_document_id:
          type: string
          nullable: true
        filed_at:
          type: string
          nullable: true
          example: '2026-11-05T15:04:05.000Z'
      required:
        - status
        - ehr
        - ehr_patient_id
        - ehr_document_id
        - filed_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.