Send a fax

curl --request POST \
  --url https://api.maxcare.ai/v3/faxes/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
  "toNumber": "(734) 714-8907",
  "idempotencyKey": "pa-renewal-2026-08-25-patient-8de03039",
  "subject": "Prior Auth Request",
  "recipientName": "McLaren Health Plan",
  "documentIds": [
    "3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607"
  ],
  "templateId": "6278"
}
'

import requests

url = "https://api.maxcare.ai/v3/faxes/send"

payload = {
    "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
    "toNumber": "(734) 714-8907",
    "idempotencyKey": "pa-renewal-2026-08-25-patient-8de03039",
    "subject": "Prior Auth Request",
    "recipientName": "McLaren Health Plan",
    "documentIds": ["3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607"],
    "templateId": "6278"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patientId: 'pat_8de030393a9e417ab2b3a8b8df183631',
    toNumber: '(734) 714-8907',
    idempotencyKey: 'pa-renewal-2026-08-25-patient-8de03039',
    subject: 'Prior Auth Request',
    recipientName: 'McLaren Health Plan',
    documentIds: ['3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607'],
    templateId: '6278'
  })
};

fetch('https://api.maxcare.ai/v3/faxes/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maxcare.ai/v3/faxes/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patientId' => 'pat_8de030393a9e417ab2b3a8b8df183631',
    'toNumber' => '(734) 714-8907',
    'idempotencyKey' => 'pa-renewal-2026-08-25-patient-8de03039',
    'subject' => 'Prior Auth Request',
    'recipientName' => 'McLaren Health Plan',
    'documentIds' => [
        '3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607'
    ],
    'templateId' => '6278'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maxcare.ai/v3/faxes/send"

	payload := strings.NewReader("{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maxcare.ai/v3/faxes/send")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v3/faxes/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "success",
  "data": {
    "id": "fax_a7c3f1e28b4d4a9eb5c6d7e8f9012345",
    "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
    "toNumber": "7347148907",
    "recipientName": "McLaren Health Plan",
    "subject": "Prior Auth Request",
    "status": "delivered",
    "errorKind": "transmission_failed",
    "statusDetail": "successfully delivered",
    "pagesSent": 15,
    "attachmentIds": [
      "201269302"
    ],
    "sentAt": "2026-08-26T03:20:20.000Z",
    "deliveredAt": "2026-08-26T03:25:00.000Z",
    "failedAt": null,
    "createdAt": "2026-08-26T03:20:19.000Z"
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "conflict",
  "message": "Cannot edit a signed note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unexpected_integration_error",
  "message": "EHR sync failed",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Faxes

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.

POST

faxes

send

Send a fax

curl --request POST \
  --url https://api.maxcare.ai/v3/faxes/send \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Organization-Id: <x-organization-id>' \
  --data '
{
  "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
  "toNumber": "(734) 714-8907",
  "idempotencyKey": "pa-renewal-2026-08-25-patient-8de03039",
  "subject": "Prior Auth Request",
  "recipientName": "McLaren Health Plan",
  "documentIds": [
    "3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607"
  ],
  "templateId": "6278"
}
'

import requests

url = "https://api.maxcare.ai/v3/faxes/send"

payload = {
    "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
    "toNumber": "(734) 714-8907",
    "idempotencyKey": "pa-renewal-2026-08-25-patient-8de03039",
    "subject": "Prior Auth Request",
    "recipientName": "McLaren Health Plan",
    "documentIds": ["3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607"],
    "templateId": "6278"
}
headers = {
    "X-Organization-Id": "<x-organization-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {
    'X-Organization-Id': '<x-organization-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    patientId: 'pat_8de030393a9e417ab2b3a8b8df183631',
    toNumber: '(734) 714-8907',
    idempotencyKey: 'pa-renewal-2026-08-25-patient-8de03039',
    subject: 'Prior Auth Request',
    recipientName: 'McLaren Health Plan',
    documentIds: ['3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607'],
    templateId: '6278'
  })
};

fetch('https://api.maxcare.ai/v3/faxes/send', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.maxcare.ai/v3/faxes/send",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patientId' => 'pat_8de030393a9e417ab2b3a8b8df183631',
    'toNumber' => '(734) 714-8907',
    'idempotencyKey' => 'pa-renewal-2026-08-25-patient-8de03039',
    'subject' => 'Prior Auth Request',
    'recipientName' => 'McLaren Health Plan',
    'documentIds' => [
        '3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607'
    ],
    'templateId' => '6278'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json",
    "X-Organization-Id: <x-organization-id>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.maxcare.ai/v3/faxes/send"

	payload := strings.NewReader("{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Organization-Id", "<x-organization-id>")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.maxcare.ai/v3/faxes/send")
  .header("X-Organization-Id", "<x-organization-id>")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.maxcare.ai/v3/faxes/send")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Organization-Id"] = '<x-organization-id>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patientId\": \"pat_8de030393a9e417ab2b3a8b8df183631\",\n  \"toNumber\": \"(734) 714-8907\",\n  \"idempotencyKey\": \"pa-renewal-2026-08-25-patient-8de03039\",\n  \"subject\": \"Prior Auth Request\",\n  \"recipientName\": \"McLaren Health Plan\",\n  \"documentIds\": [\n    \"3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607\"\n  ],\n  \"templateId\": \"6278\"\n}"

response = http.request(request)
puts response.read_body

{
  "code": "success",
  "data": {
    "id": "fax_a7c3f1e28b4d4a9eb5c6d7e8f9012345",
    "patientId": "pat_8de030393a9e417ab2b3a8b8df183631",
    "toNumber": "7347148907",
    "recipientName": "McLaren Health Plan",
    "subject": "Prior Auth Request",
    "status": "delivered",
    "errorKind": "transmission_failed",
    "statusDetail": "successfully delivered",
    "pagesSent": 15,
    "attachmentIds": [
      "201269302"
    ],
    "sentAt": "2026-08-26T03:20:20.000Z",
    "deliveredAt": "2026-08-26T03:25:00.000Z",
    "failedAt": null,
    "createdAt": "2026-08-26T03:20:19.000Z"
  }
}

{
  "code": "bad_request",
  "message": "'id' must be a valid UUID",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unauthorized",
  "message": "Invalid or missing API key",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "forbidden",
  "message": "Insufficient scope",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "not_found",
  "message": "Resource not found",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "conflict",
  "message": "Cannot edit a signed note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Maximum 1000 requests per 60 seconds.",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "unexpected_integration_error",
  "message": "EHR sync failed",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

{
  "code": "server_unresponsive",
  "message": "EHR integration is not available for this note",
  "trace_id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

Authorization

string

header

required

Marketplace API key

Headers

X-Organization-Id

string

required

Target clinic organization ID

Body

application/json

patientId

string

required

Patient whose chart the fax is sent from

Example:

"pat_8de030393a9e417ab2b3a8b8df183631"

toNumber

string

required

Destination fax number (10-digit US, punctuation allowed)

Example:

"(734) 714-8907"

idempotencyKey

string

required

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"

subject

string

Line printed on the cover page

Example:

"Prior Auth Request"

recipientName

string

Recipient name, recorded with the send

Example:

"McLaren Health Plan"

documentIds

string[]

Chart documents to attach, by the IDs returned from GET /patients/{id}/documents

Example:

["3f2a1b4c-5d6e-4f70-8a91-b2c3d4e5f607"]

file

object

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.

Show child attributes

templateId

string

Cover-page template ID from GET /faxes/templates. Defaults to the practice's document template.

Example:

"6278"

Response

Success

code

string

required

Response code

Example:

"success"

data

object

required

Show child attributes