Sending a Fax

The Fax Service allows you to send faxes to providers and patients with a single API call. This feature is fully integrated with the FHIR datastore, documenting each fax transmission as a Communication (opens in a new tab) resource. You can use Fax to send referrals, medical records, prescriptions, and other documents that require fax transmission.

Preparing to Send a Fax

Before sending a fax, you'll need:

A fax number onboarded to your project.
An updated access policy to allow sending faxes using the Fax:Send action over all Fax:Fax:* resources.
The document to fax — Must be uploaded to your project's Z3 storage first. The document must be accessible by the sender.
The recipient and sender FHIR resources — The recipient can be one of: CareTeam, HealthcareService, Organization, Patient, Practitioner, PractitionerRole, RelatedPerson. The sender can be one of: HealthcareService, Organization, Patient, Practitioner, PractitionerRole, RelatedPerson. If you do not have one of these resources and just want to send a fax to an arbitrary number, provide the recipientNumber property instead.

Both FHIR resources must have a telecom property with a system of fax and a value that is a valid fax number in E.164 format. The sender's fax number must be the same one onboarded in step 1. For example:

{
  "resourceType": "HealthcareService",
  "id": "79ac80be-e0c5-4d15-8733-dcadd807f964",
  "telecom": [
    {
      "system": "fax",
      "value": "+12223334444"
    }
  ],
  // ...
}

Sending a Fax

Once you have your FHIR resources and document in place, you can send a fax with a single API call:

Send a Fax using the v3 SDK and the recipient property

import Oystehr from '@oystehr/sdk';
 
const oystehr = new Oystehr({
  accessToken: "<your_access_token>",
});
 
const response = await oystehr.fax.send({
  media: "https://project-api.zapehr.com/v1/z3/my-bucket/path/to/document.pdf",
  quality: "standard", // options: standard, fine, superfine
  recipient: "Practitioner/51940f7e-7311-4006-b9aa-83bbc0c5b62c",
  sender: "HealthcareService/79ac80be-e0c5-4d15-8733-dcadd807f964"
});

A successful response would return:

{
    "communicationResource": {
        "resourceType": "Communication",
        "medium": [
            {
                "coding": [
                    {
                        "system": "https://terminology.hl7.org/6.0.2/ValueSet-v3-ParticipationMode.html",
                        "code": "FAXWRIT",
                        "display": "telefax"
                    }
                ],
                "text": "telefax"
            }
        ],
        "payload": [
            {
                "contentAttachment": {
                    "url": "https://project-api.zapehr.com/v1/z3/my-bucket/path/to/document.pdf"
                }
            }
        ],
        "recipient": [
            {
                "reference": "Practitioner/51940f7e-7311-4006-b9aa-83bbc0c5b62c"
            }
        ],
        "sender": {
            "reference": "HealthcareService/79ac80be-e0c5-4d15-8733-dcadd807f964"
        },
        "sent": "2024-11-12T10:06:34.292Z",
        "status": "in-progress",
        "id": "bc32059c-15c8-4d4c-851b-3f893aca7a31",
        "meta": {
            "versionId": "081facde-3160-4ecd-937c-fd8d559ee088",
            "lastUpdated": "2024-11-12T10:06:35.666Z"
        },
        "identifier": [
            {
                "system": "https://identifiers.oystehr.com/fax",
                "value": "c98f7c87-24c8-4b26-8aa4-942bc87f0873",
                "type": {
                    "coding": [
                        {
                            "system": "https://terminology.fhir.oystehr.com/CodeSystem/fax",
                            "code": "FAX-ID",
                            "display": "Fax ID",
                            "version": "1.0.0"
                        }
                    ]
                }
            }
        ],
        "extension": [
            {
                "url": "https://extensions.fhir.oystehr.com/outbound-fax-status",
                "valueCodeableConcept": {
                    "coding": [
                        {
                            "system": "https://terminology.fhir.oystehr.com/CodeSystem/outbound-fax-status",
                            "code": "QUEUED",
                            "display": "queued"
                        }
                    ],
                    "text": "queued"
                }
            }
        ]
    }
}

A successful response using recipientNumber would return a similar resource with these differences:

{
    ...
    "recipient": [
        {
            "reference": "#+12223334444"
        }
    ],
    ...
    "contained": [
        {
            resourceType: 'Practitioner',
            id: "+12223334444",
            telecom: [
                {
                    system: 'fax',
                    value: "+12223334444",
                },
            ],
        },
    ],
    ...
}

In both cases, if the patient property is provided, it will be added as a reference in the Communication resource's subject. This enables searching for all faxes related to a specific patient, for example.

Fax Status Tracking

When you send a fax, the FHIR Communication resource is automatically updated to track its status. If successful, the status usually goes through the following stages:

queued
processing
sending
delivered

If for any reason the fax fails to send, the Communication resource's status will be stopped and its statusReason will include the failure reason. See Fax Failure Reasons for the full list of codes and messages.

🚧

The Fax Service does not yet support FHIR R5.

Fax Service Configuration Receiving a Fax