🚧

Sending a Fax

The Fax feature 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.
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.

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

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"
                }
            }
        ]
    }
}

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.

🚧

The Fax feature does not yet support FHIR R5.

Registering a Fax Number Welcome