eFax Integration | Medplum

On this page

Medplum provides a first-party integration with eFax Corporate to send and receive faxes directly from your healthcare application. Faxes are stored as FHIR Communication resources, enabling seamless integration with your clinical workflows.

Medplum Team Setup Required

This integration requires setup by the Medplum team. Contact us to enable eFax for your project.

Planning this integration?

The Messaging & Communications Decision Guide walks through requirements questions and FHIR modeling decisions for messaging — thread structure, routing, and external channels — use it alongside these docs.

Overview

The eFax integration allows you to:

Send faxes from FHIR Communication resources via the $send-efax operation
Receive faxes and store them as Communication resources via the $receive-efax operation
Test connectivity to verify your eFax API configuration

Prerequisites

Before using the eFax integration, you must have:

The eFax integration enabled on your Medplum project (contact the Medplum team)
eFax API credentials configured as project secrets

Configuration

Project Secrets

The following secrets must be configured in your Medplum project:

Secret Name	Description
`eFaxAppId`	Your eFax application ID
`eFaxApiKey`	Your eFax API key
`eFaxUserId`	Default eFax user ID for system-level operations

FHIR Operations

`$receive-efax` - Receive Faxes

Poll for and receive faxes from eFax, creating Communication resources for each new fax. Depending on how you configure your eFax account, you can call this operation on the system level, on an Organization level, or on a Practitioner level.

For the simplest setup, if you only need one fax number, we recommend calling /fhir/R4/Communication/$receive-efax to start.

Endpoint	Use Case	User ID Source
`POST /fhir/R4/Communication/$receive-efax`	Clinic-wide shared fax	Project secret `eFaxUserId`
`POST /fhir/R4/Organization/{id}/$receive-efax`	Department/location fax	Organization's eFax identifier
`POST /fhir/R4/Practitioner/{id}/$receive-efax`	Individual practitioner fax	Practitioner's eFax identifier

Resource Configuration

For practitioners or organizations to send/receive faxes, add their eFax user ID as an identifier:

{

"resourceType": "Practitioner",

"identifier": [
    {
      "system": "https://efax.com",
      "value": "<EFAX_USER_ID>"
    }
  ],

"telecom": [
    {
      "system": "fax",
      "value": "+15551234567"
    }
  ]
}

`$send-efax` - Send a Fax

Send a fax from a Communication resource.

Endpoint	Description
`POST /fhir/R4/Communication/$send-efax`	Send a fax from a Communication resource

Request Body: A Communication resource with:

medium containing code FAXWRIT from system http://terminology.hl7.org/CodeSystem/v3-ParticipationMode
payload with either a contentReference to a DocumentReference (recommended) or an inline contentAttachment containing the document to fax (PDF, JPEG, or PNG)
sender reference to a Practitioner with eFax identifier
recipient reference(s) to resources with fax numbers in their telecom

Recipient fax numbers must be in E.164 format: a leading + followed by the country calling code and the subscriber number (for example, +1 for US/Canada, then the number: +15551234567). eFax requires this country code; a local number without it may fail or route incorrectly.

Example: Sending a Fax

import { createReference } from '@medplum/core';

import type { Communication, DocumentReference, Organization, Practitioner } from '@medplum/fhirtypes';

// Assuming you have a MedplumClient instance and the sender's Practitioner profile

const profile = await medplum.getProfile() as Practitioner;

// Step 1: Upload the file and persist it as a DocumentReference (creates a Binary resource)

// so the faxed document is tracked in the chart, not just embedded on the Communication.

const attachment = await medplum.createAttachment({

data: file,  // File object from input

contentType: file.type,

filename: file.name,

});

const documentReference = await medplum.createResource<DocumentReference>({

resourceType: 'DocumentReference',

status: 'current',

author: [createReference(profile)],

date: new Date().toISOString(),

content: [{ attachment }],

});

// Step 2: Create the recipient Organization (fax value must be E.164: + and country code)

const recipient = await medplum.createResource<Organization>({

resourceType: 'Organization',

name: 'Acme Medical Center',

contact: [{ telecom: [{ system: 'fax', value: '+15551234567' }] }],

});

// Step 3: Create the Communication with proper references

const communication = await medplum.createResource<Communication>({

resourceType: 'Communication',

status: 'in-progress',

category: [{ coding: [{ system: 'http://medplum.com/fhir/CodeSystem/fax-direction', code: 'outbound' }] }],

medium: [
    {
      coding: [
        {
          system: 'http://terminology.hl7.org/CodeSystem/v3-ParticipationMode',
          code: 'FAXWRIT',
        },
      ],
    },
  ],

sender: createReference(profile),

recipient: [createReference(recipient)],

payload: [{ contentReference: createReference(documentReference) }],

});

// Step 4: Call the $send-efax operation

await medplum.post(medplum.fhirUrl('Communication', '$send-efax'), communication);

console.log('Fax sent successfully!');

Communication Resource Structure

The samples below show the Communication resource only. For outbound sends, the fax number used by eFax comes from the recipient resource’s telecom and must include the country code in E.164 form (e.g. +15551234567), as in the Organization recipient example above.

Outbound Fax (Sent)

{

"resourceType": "Communication",

"status": "in-progress",

"identifier": [
    {
      "system": "https://efax.com",
      "value": "fax-12345"
    }
  ],

"medium": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
          "code": "FAXWRIT",
          "display": "telefax"
        }
      ]
    }
  ],

"sender": {
    "reference": "Practitioner/sender-id"
  },

"recipient": [
    {
      "reference": "Practitioner/recipient-id"
    }
  ],

"sent": "2025-01-15T10:30:00Z",

"category": [
    {
      "coding": [
        {
          "system": "http://medplum.com/fhir/CodeSystem/fax-direction",
          "code": "outbound"
        }
      ]
    }
  ],

"payload": [
    {
      "contentReference": {
        "reference": "DocumentReference/document-id"
      }
    }
  ]
}

Inbound Fax (Received)

{

"resourceType": "Communication",

"status": "completed",

"identifier": [
    {
      "system": "https://efax.com",
      "value": "fax-67890"
    }
  ],

"medium": [
    {
      "coding": [
        {
          "system": "http://terminology.hl7.org/CodeSystem/v3-ParticipationMode",
          "code": "FAXWRIT",
          "display": "telefax"
        }
      ]
    }
  ],

"recipient": [
    {
      "reference": "Practitioner/recipient-id"
    }
  ],

"sent": "2025-01-15T09:15:00Z",

"payload": [
    {
      "contentAttachment": {
        "url": "Binary/received-fax-id",
        "contentType": "application/pdf",
        "title": "fax-67890.pdf"
      }
    }
  ],

"category": [
    {
      "coding": [
        {
          "system": "http://medplum.com/fhir/CodeSystem/fax-direction",
          "code": "inbound"
        }
      ]
    }
  ]
}

Supported Document Types

The following content types are supported for sending faxes:

Content Type	Extension
`application/pdf`	.pdf
`image/jpeg`	.jpg, .jpeg
`image/png`	.png

Example Application

See the medplum-efax-demo example for a complete React application demonstrating the eFax integration.