Receiving a Fax

The Fax Service automatically receives inbound faxes sent to your project's fax number. When a fax is received, it is stored in your project's Z3 storage and documented as a Communication (opens in a new tab) resource in the FHIR datastore.

How It Works

When someone sends a fax to your project's number, the following happens automatically:

Fax Reception — The incoming fax transmission is received
Storage — The fax PDF is automatically uploaded to a dedicated Z3 bucket ({projectUuid}-fax-received)
FHIR Documentation — A Communication resource is created with details about the sender, recipient, and the fax document

Accessing Received Faxes

Received faxes are stored as Communication resources with:

Status: completed for successfully received faxes, stopped for failed receptions
Direction: Identified by the extension https://extensions.fhir.oystehr.com/inbound-fax-status
Document: Available in the payload with a URL pointing to the Z3-stored PDF

Example: Searching for Received Faxes

You can search for all received faxes using the FHIR API:

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
// Search for all received faxes
const faxes = await oystehr.fhir.search({
  resourceType: 'Communication',
  params: [
    {
      name: 'medium',
      value: 'FAXWRIT'
    }
  ]
});

Communication Resource Structure

A received fax creates a Communication resource with the following structure:

{
  "resourceType": "Communication",
  "id": "bc32059c-15c8-4d4c-851b-3f893aca7a31",
  "identifier": [
    {
      "system": "https://identifiers.oystehr.com/fax",
      "value": "2cf1a7b9-314f-46e8-a96e-d1d56de98a59",
      "type": {
        "coding": [
          {
            "system": "https://terminology.fhir.oystehr.com/CodeSystem/fax",
            "code": "FAX-ID",
            "display": "Fax ID",
            "version": "1.0.0"
          }
        ]
      }
    }
  ],
  "status": "completed",
  "medium": [
    {
      "coding": [
        {
          "system": "https://terminology.hl7.org/6.0.2/ValueSet-v3-ParticipationMode.html",
          "code": "FAXWRIT",
          "display": "telefax"
        }
      ],
      "text": "telefax"
    }
  ],
  "sender": {
    "reference": "#+15165483859"
  },
  "recipient": [
    {
      "reference": "#+12345678901"
    }
  ],
  "contained": [
    {
      "resourceType": "Practitioner",
      "id": "+15165483859",
      "telecom": [
        {
          "system": "fax",
          "value": "+15165483859"
        }
      ],
      "identifier": [
        {
          "system": "https://identifiers.oystehr.com/remote-station-id",
          "value": "FaxZero.com"
        }
      ]
    },
    {
      "resourceType": "Practitioner",
      "id": "+12345678901",
      "telecom": [
        {
          "system": "fax",
          "value": "+12345678901"
        }
      ]
    }
  ],
  "payload": [
    {
      "contentAttachment": {
        "url": "https://z3.oystehr.com/95753a75-6891-4097-8d5c-b90dfe18b897-fax-received/2025/01/10/2cf1a7b9-314f-46e8-a96e-d1d56de98a59.pdf",
        "contentType": "application/pdf"
      }
    }
  ],
  "extension": [
    {
      "url": "https://extensions.fhir.oystehr.com/inbound-fax-status",
      "valueCodeableConcept": {
        "coding": [
          {
            "system": "https://terminology.fhir.oystehr.com/CodeSystem/inbound-fax-status",
            "code": "RECEIVED",
            "display": "received"
          }
        ],
        "text": "received"
      }
    },
    {
      "url": "https://extensions.fhir.oystehr.com/fax-pages",
      "valueInteger": 3
    }
  ],
  "sent": "2025-01-10T19:14:59Z",
  "received": "2025-01-10T19:14:59Z"
}

Failed Faxes

If a fax fails to be received (e.g., incompatible format, connection issues), the Communication resource will have:

status: stopped
extension[inbound-fax-status]: Code FAILED
statusReason: Error details

Failed faxes may not include page count or document URL if the failure occurred before the fax content could be processed.

Configuration

Inbound fax handling is automatically configured when you onboard your fax number.

🚧

The Fax Service does not yet support FHIR R5 (opens in a new tab).

Sending a Fax FHIR