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

# Send a fax

> Faxes chart documents and/or an uploaded file from a patient's chart to a fax number, through the practice's own EHR fax subsystem. **Anything sent as `file` is filed as a document on the patient's chart on the way out** — that is how the EHR faxes — so it becomes part of the medical record. A sent fax cannot be recalled, so `idempotencyKey` is required: a repeat with the same key never dials, it returns the original record (see that field). The returned `status` is `sent`, meaning the EHR accepted it, NOT that anything arrived; it settles to `delivered` or `failed` within minutes, readable here or via the `fax.status_changed` webhook. `delivered` means the receiving machine accepted the pages — it does not mean a human has worked the fax.



## OpenAPI

````yaml /openapi-v4.json post /faxes/send
openapi: 3.0.0
info:
  title: Max AI Public API
  description: API for third-party marketplace apps
  version: '4.0'
  contact: {}
servers:
  - url: https://api.maxcare.ai/v4
security: []
tags: []
paths:
  /faxes/send:
    post:
      tags:
        - Faxes
      summary: Send a fax
      description: >-
        Faxes chart documents and/or an uploaded file from a patient's chart to
        a fax number, through the practice's own EHR fax subsystem. **Anything
        sent as `file` is filed as a document on the patient's chart on the way
        out** — that is how the EHR faxes — so it becomes part of the medical
        record. A sent fax cannot be recalled, so `idempotencyKey` is required:
        a repeat with the same key never dials, it returns the original record
        (see that field). The returned `status` is `sent`, meaning the EHR
        accepted it, NOT that anything arrived; it settles to `delivered` or
        `failed` within minutes, readable here or via the `fax.status_changed`
        webhook. `delivered` means the receiving machine accepted the pages — it
        does not mean a human has worked the fax.
      operationId: FaxesPublicController_sendFax
      parameters:
        - name: X-Organization-Id
          in: header
          required: true
          schema:
            type: string
          description: Target clinic organization ID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SendFaxBodyV3'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendFaxSuccessResponseV3'
        '400':
          description: Missing or invalid request parameter
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiBadRequestResponse'
        '401':
          description: Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiUnauthorizedResponse'
        '403':
          description: Insufficient scope
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiForbiddenResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiNotFoundResponse'
        '409':
          description: Resource conflict (e.g. editing a signed note)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiConflictResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiRateLimitResponse'
        '502':
          description: EHR sync failed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiBadGatewayResponse'
        '503':
          description: EHR integration unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiServiceUnavailableResponse'
      security:
        - api-key: []
components:
  schemas:
    SendFaxBodyV3:
      type: object
      properties:
        patientId:
          type: string
          description: Patient whose chart the fax is sent from
          example: pat_8de030393a9e417ab2b3a8b8df183631
        toNumber:
          type: string
          description: Destination fax number (10-digit US, punctuation allowed)
          example: (734) 714-8907
        subject:
          type: string
          description: Line printed on the cover page
          example: Prior Auth Request
        recipientName:
          type: string
          description: Recipient name, recorded with the send
          example: McLaren Health Plan
        documentIds:
          description: >-
            Chart documents to attach, by the IDs returned from GET
            /patients/{id}/documents
          example:
            - 3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607
          type: array
          items:
            type: string
        file:
          description: >-
            A file to fax that is not yet in the chart. NOTE: faxing happens
            from the chart, so this file is filed as a chart document and
            becomes part of the medical record.
          allOf:
            - $ref: '#/components/schemas/SendFaxFileBody'
        templateId:
          type: string
          description: >-
            Cover-page template ID from GET /faxes/templates. Defaults to the
            practice's document template.
          example: '6278'
        idempotencyKey:
          type: string
          description: >-
            Caller-generated key that makes this send idempotent. **A repeat
            with the same key never dials**: it returns the original fax record
            as it currently stands — including a `failed` one — so re-asking
            after an unknown outcome is always safe, and clearing a stuck row
            can never put a second copy on the recipient's machine. While the
            first send is still in flight you get `503` — repeat the SAME
            request shortly, and never mint a new key for it: that would put a
            second copy on the recipient's machine. A `409` is a different thing
            entirely — the key was already used for a DIFFERENT fax, and only
            then is a new key the right answer. To deliberately send again, use
            a NEW key. Two sends match when the patient, destination,
            attachments, inline file (bytes, name and type), subject and cover
            template match; `recipientName` is NOT part of that comparison,
            because it is recorded with the fax but never reaches the EHR or the
            printed page. The key is scoped to (your app, this organization), is
            honoured for the life of the fax record, and never expires.
          example: pa-renewal-2026-08-25-patient-8de03039
      required:
        - patientId
        - toNumber
        - idempotencyKey
    SendFaxSuccessResponseV3:
      type: object
      properties:
        code:
          type: string
          description: Response code
          example: success
        data:
          $ref: '#/components/schemas/ExternalFaxResponseV3'
      required:
        - code
        - data
    PublicApiBadRequestResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: bad_request
        message:
          type: string
          description: Human-readable error message
          example: '''id'' must be a valid UUID'
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiUnauthorizedResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: unauthorized
        message:
          type: string
          description: Human-readable error message
          example: Invalid or missing API key
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiForbiddenResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: forbidden
        message:
          type: string
          description: Human-readable error message
          example: Insufficient scope
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiNotFoundResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: not_found
        message:
          type: string
          description: Human-readable error message
          example: Resource not found
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiConflictResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: conflict
        message:
          type: string
          description: Human-readable error message
          example: Cannot edit a signed note
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiRateLimitResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: rate_limit_exceeded
        message:
          type: string
          description: Human-readable error message
          example: Rate limit exceeded. Maximum 1000 requests per 60 seconds.
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiBadGatewayResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: unexpected_integration_error
        message:
          type: string
          description: Human-readable error message
          example: EHR sync failed
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    PublicApiServiceUnavailableResponse:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: server_unresponsive
        message:
          type: string
          description: Human-readable error message
          example: EHR integration is not available for this note
        trace_id:
          type: string
          description: Trace ID for debugging
          example: 550e8400-e29b-41d4-a716-446655440000
      required:
        - code
        - message
        - trace_id
    SendFaxFileBody:
      type: object
      properties:
        fileName:
          type: string
          description: File name shown in the chart and on the fax
          example: McLaren_PA_Request.pdf
        mimeType:
          type: string
          description: File MIME type
          example: application/pdf
          enum:
            - application/pdf
        contentBase64:
          type: string
          description: >-
            File bytes, base64 encoded (no data: prefix). Line breaks are
            accepted and ignored.
          example: JVBERi0xLjQK...
      required:
        - fileName
        - mimeType
        - contentBase64
    ExternalFaxResponseV3:
      type: object
      properties:
        id:
          type: string
          description: Fax record ID
          example: fax_a7c3f1e28b4d4a9eb5c6d7e8f9012345
        patientId:
          type: string
          description: Patient the fax was sent for
          example: pat_8de030393a9e417ab2b3a8b8df183631
        toNumber:
          type: string
          description: Destination fax number, normalized to digits
          example: '7347148907'
        recipientName:
          type: string
          description: Recipient name when supplied
          nullable: true
          example: McLaren Health Plan
        subject:
          type: string
          description: Cover page line
          nullable: true
          example: Prior Auth Request
        status:
          type: string
          description: >-
            Delivery status. `sent` means the EHR accepted it and delivery is
            not yet confirmed; it settles to `delivered` or `failed` within
            minutes.
          enum:
            - sent
            - delivered
            - failed
          example: delivered
        errorKind:
          type: string
          description: >-
            Why a failed fax failed. Null unless status is failed. One of
            `ehr_send_failed` (the EHR refused the send), `invalid_request` (the
            number or the attachment is wrong — retrying the same request cannot
            help), `transmission_failed` (busy, no answer, not a fax machine),
            `not_found_in_outbox`, `ambiguous_outbox_match`, `still_processing`,
            `send_interrupted`, `patient_unresolvable`, `outbox_unreadable`,
            `unknown_status`. Only the first three are definite.
            `not_found_in_outbox` and everything after it mean the outcome is
            UNKNOWN — the fax may have been delivered, so do not blind-retry.
          nullable: true
          example: transmission_failed
        statusDetail:
          type: string
          description: The EHR's own description of the outcome
          nullable: true
          example: successfully delivered
        pagesSent:
          type: number
          description: Pages transmitted, once known
          nullable: true
          example: 15
        attachmentIds:
          description: Chart document IDs (EHR-native) that were faxed
          example:
            - '201269302'
          type: array
          items:
            type: string
        sentAt:
          type: string
          description: >-
            When the send was issued to the EHR — anchored just BEFORE the
            request, because it is the floor the outbox correlation matches
            against. It is not an acceptance time and not a delivery time: a
            `failed` fax carries one too. Read `status` and `errorKind` for what
            actually happened.
          example: '2026-08-26T03:20:20.000Z'
        deliveredAt:
          type: string
          description: When delivery was confirmed
          nullable: true
          example: '2026-08-26T03:25:00.000Z'
        failedAt:
          type: string
          description: When the fax terminally failed
          nullable: true
          example: null
        createdAt:
          type: string
          description: Created timestamp
          example: '2026-08-26T03:20:19.000Z'
      required:
        - id
        - patientId
        - toNumber
        - recipientName
        - subject
        - status
        - errorKind
        - statusDetail
        - pagesSent
        - attachmentIds
        - sentAt
        - deliveredAt
        - failedAt
        - createdAt
  securitySchemes:
    api-key:
      scheme: bearer
      bearerFormat: JWT
      type: http
      description: Marketplace API key

````