Received Faxes

Use API v3 to work with the same native fax documents your team uses in the Medsender web app. One developer account is explicitly linked to one customer organization.

Using /api/v2? See the legacy received fax reference.

Where self-serve is offered for your account, verify email, complete the BAA, choose your fax number and add a card. Successful activation links your organization automatically. Enterprise and manual integrations coordinate enrollment with Medsender. Signup or key creation alone does not enable v3. After activation or enrollment, test keys support simulated sent-fax operations; received-fax operations require live keys.

Access and prerequisites

  • Use a developer credential with a confirmed, active account and approved BAA coverage under Medsender’s existing eligibility policy. The live examples use a Bearer live key. Test keys support simulated sent-fax operations after the same enrollment; received-fax operations require a live key. Organization API credentials cannot authorize v3.
  • Your developer account must be explicitly linked to the organization. Where self-serve is offered for your account, successful activation creates this link automatically after email verification, BAA completion, number selection and card setup. Enterprise and manual integrations coordinate the link with Medsender. Access is organization-wide, including department and private fax documents, independent of an employee’s inbox permissions. Web-user permissions remain separate.
  • Sending and archiving require a configured active organization member for attribution. Removing that member prevents those writes; the organization grant still controls reads.
  • Sending requires an active fax number owned by the linked organization. Where self-serve is offered for your account, choose your included number before activation and manage its HTTPS callback on Fax Numbers once live; additional purchases require Medsender support. Enterprise and manual integrations coordinate number setup and incoming routing with Medsender. Configure the live webhook secret for callback verification. Do not provision or move developer-owned numbers through v2 expecting v3 access.
bash
# Use after successful self-serve activation or enterprise enrollment.
export API_BASE="https://api.medsender.com/api/v3"
export API_KEY="sk_live_REPLACE_WITH_YOUR_KEY"
# Use after successful self-serve activation or enterprise enrollment.
export API_BASE="https://api.medsender.com/api/v3"
export API_KEY="sk_live_REPLACE_WITH_YOUR_KEY"

These examples send real faxes with live credentials. Replace the numbers with your configured sender and an authorized destination. Use only an approved sample document.

Limits and errors

Self-serve accounts have fixed limits: $100 of spend per rolling 30 days, at 3¢ per page sent or received; 10¢ per received page with AI. Each fax still sending holds $6 of the limit until it finishes, so the limit can be reached before $100 is billed. Received faxes are always accepted and count toward the limit.

AI for incoming faxes is off by default. Once live faxing is on, you can turn it on from the Fax billing & limits page. With AI on, each received page costs 10¢ (3¢ fax + 7¢ AI) instead of 3¢, and those AI pages count toward the $100 limit like the rest of your usage.

  • 402 SPEND_LIMIT_REACHED: the send would take the last 30 days over $100. Nothing is sent or stored. Retry once older usage leaves the window, or contact support@medsender.com to raise your limit.
  • 402 PAYMENT_REQUIRED: live sending is paused for a billing issue. Update your payment method on the Fax billing & limits page; if that doesn't restore it, contact Medsender support. Received faxes can still be read.

Both use the 402 status, so check the error code to tell them apart.

Endpoints

Paths below are relative to /api/v3. Requests use snake_case fields; JSON responses use camelCase. Fax IDs are the opaque sendToken values, not database IDs.

Method and pathResult
GET /received_faxesNative received list in receivedFaxes plus pagination meta.
GET /received_faxes/:idreceivedFax object with pdfDownloadUrl.
PATCH /received_faxes/:idArchive/unarchive; receivedFax without a download URL.

List and filter faxes

bash
curl --fail-with-body -sS --get "$API_BASE/received_faxes" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=10" \
  --data-urlencode "archived=false"
curl --fail-with-body -sS --get "$API_BASE/received_faxes" \
  -H "Authorization: Bearer $API_KEY" \
  --data-urlencode "page=1" \
  --data-urlencode "page_size=10" \
  --data-urlencode "archived=false"

Received filters: from_number, to_number, patient_name, dob (or patient_dob), date_start, date_end and archived. Received results are ordered by date; use sort_dir=asc or desc. from_number matches the complete sender number. Use E.164 (+13125550123), 11 digits (13125550123), 10 digits (3125550123) or a formatted number ((312) 555-0123). Partial numbers and invalid lengths return 400.

Use YYYY-MM-DD for DOB and calendar-date filters, for example 1965-03-14; avoid slash-formatted dates. Date ranges also accept ISO 8601 timestamps. Lists accept page and page_size (1–100). Pagination is in meta.totalCount, totalPages, perPage and page. List rows identify faxes with sendToken; fetch detail for a PDF link.

Receive and download

Receive a fax on the organization’s configured native fax number, then find it in receivedFaxes. Native received faxes are successful inbound transmissions; emailed secure-document deliveries and legacy developer-owned history are outside this resource.

bash
export RECEIVED_TOKEN="example-received-token" # sendToken from receivedFaxes
curl --fail-with-body -sS "$API_BASE/received_faxes/$RECEIVED_TOKEN" \
  -H "Authorization: Bearer $API_KEY"
export RECEIVED_TOKEN="example-received-token" # sendToken from receivedFaxes
curl --fail-with-body -sS "$API_BASE/received_faxes/$RECEIVED_TOKEN" \
  -H "Authorization: Bearer $API_KEY"

Response excerpt:

JSON
{
  "receivedFax": {
    "sendToken": "example-received-token",
    "faxStatus": "success",
    "archived": false,
    "pdfDownloadUrl": "https://storage.example.com/signed-current-document.pdf",
    "aiResult": {
      "status": "successful",
      "skipReason": null,
      "completedAt": "2026-10-07T12:02:00Z",
      "documentTitle": "Synthetic Referral",
      "patientName": "Synthetic Q Patient",
      "patientFirstName": "Synthetic",
      "patientMiddleName": "Q",
      "patientLastName": "Patient",
      "patientDob": "1990-01-02",
      "patientGender": "Male",
      "patientPhoneNumber": "312-555-0199",
      "patientEmail": "synthetic@example.test",
      "patientAddress": "100 Synthetic Street",
      "patientCity": "Chicago",
      "patientState": "IL",
      "patientZipCode": "60601",
      "providerOffice": null,
      "practitionerName": null,
      "referringProvider": null,
      "primaryPlan": "Synthetic Plan",
      "primaryPlanName": "Synthetic Plan",
      "primaryMemberId": "MEM-1",
      "secondaryPlan": null,
      "secondaryPlanName": null,
      "secondaryMemberId": null,
      "documentSummary": "Synthetic referral for follow-up.",
      "dateOfService": null,
      "classification": null
    }
  }
}
{
  "receivedFax": {
    "sendToken": "example-received-token",
    "faxStatus": "success",
    "archived": false,
    "pdfDownloadUrl": "https://storage.example.com/signed-current-document.pdf",
    "aiResult": {
      "status": "successful",
      "skipReason": null,
      "completedAt": "2026-10-07T12:02:00Z",
      "documentTitle": "Synthetic Referral",
      "patientName": "Synthetic Q Patient",
      "patientFirstName": "Synthetic",
      "patientMiddleName": "Q",
      "patientLastName": "Patient",
      "patientDob": "1990-01-02",
      "patientGender": "Male",
      "patientPhoneNumber": "312-555-0199",
      "patientEmail": "synthetic@example.test",
      "patientAddress": "100 Synthetic Street",
      "patientCity": "Chicago",
      "patientState": "IL",
      "patientZipCode": "60601",
      "providerOffice": null,
      "practitionerName": null,
      "referringProvider": null,
      "primaryPlan": "Synthetic Plan",
      "primaryPlanName": "Synthetic Plan",
      "primaryMemberId": "MEM-1",
      "secondaryPlan": null,
      "secondaryPlanName": null,
      "secondaryMemberId": null,
      "documentSummary": "Synthetic referral for follow-up.",
      "dateOfService": null,
      "classification": null
    }
  }
}

Fetch receivedFax.pdfDownloadUrl directly. It expires after two minutes and can be null when the PDF is unavailable. Request detail again for a fresh link. The received download follows the current web document, so saved web edits change subsequent downloads.

Incoming fax AI

Incoming AI is available by coordinated enrollment and must be enabled for your account. The received list, detail, archive response and incoming callback expose the same nested aiResult. Your team can review the original extraction in the web app’s AI Fields tab. Edits to the document or patient information do not rewrite the completed extraction.

Fax delivery and AI completion are separate: faxStatus=success means the document arrived. Poll detail and inspect aiResult.status for extraction progress:

  • in_progress: AI is running or retrying. The incoming callback waits for completion.
  • successful: the web extraction completed; absent values are null.
  • failed: the web extraction could not establish usable patient information, enrollment was revoked, or extraction exhausted its retries. The fax remains available; terminal notification follows the callback’s current authorization.
  • skipped: no API AI extraction was admitted. The callback is sent immediately. Organization web AI can still run under its own enabled features; skipped API results contain null extraction fields and no API AI charge. skipReason distinguishes ai_disabled, spend_cap_reached, spend_guard_unavailable, blacklisted, trial_expired, page_count_unavailable or enrollment_revoked.
  • unavailable: no API AI result is available for this fax. Historical web extractions are not backfilled into API results.

The result uses the web app’s existing extraction: documentTitle and documentSummary; patient name, DOB, gender, phone, email and address; providerOffice, practitionerName and referringProvider; primary and secondary plan names and member IDs; dateOfService and classification. Provider, insurance and classification enrichment follows your organization’s enabled web features. Fields that are absent or unavailable are null. Dates use YYYY-MM-DD. completedAt is the AI completion time, separate from the fax’s transmission time. Extraction follows your organization’s web pipeline configuration; the default unified step processes up to 35 pages.

primaryPlan and primaryPlanName are aliases for the extracted primary plan name. secondaryPlan and secondaryPlanName are aliases for the extracted secondary plan name.

For the self-serve fax plan, transmission is 3¢ per original received page and successful AI adds 7¢ per original page. Skipped and failed AI are not charged for extraction. Pending work reserves spend against the shared cap; reaching the cap skips AI while preserving the incoming fax and its transmission charge. Confirm plan eligibility, spend protection and native billing setup with Medsender before enrollment.

Archive or unarchive

bash
curl --fail-with-body -sS -X PATCH "$API_BASE/received_faxes/$RECEIVED_TOKEN" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"received_fax":{"archived":true}}'
curl --fail-with-body -sS -X PATCH "$API_BASE/received_faxes/$RECEIVED_TOKEN" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"received_fax":{"archived":true}}'

The received_fax wrapper and boolean archived field are required. Set it to false to unarchive. The 200 response contains receivedFax.archived; pdfDownloadUrl is null. Archiving changes the organization’s web fax state and is attributed to the configured member. It does not delete the document.

Callbacks and access changes

V3 sends retain the initiating integration for terminal callbacks, delivered to the sender fax number’s configured callback URL. A per-send callback_url does not override that configuration. Explicitly enrolled native incoming callbacks use the selected integration and the configured number callback URL. Configure the live portal webhook secret for live traffic and the test secret for simulated sends. These callbacks add X-Medsender-Signature-V2 while retaining the legacy signature header. Follow the callback signature verification guide, including the incoming file digest, and handle duplicate notifications: delivery is at least once.

Incoming callbacks are multipart POSTs with recordDetails containing a serialized JSON object and file containing the PDF. They include the native fax metadata and nested aiResult, matching the API extraction. An admitted AI run delays the callback until successful or failed; skipped AI is delivered immediately. The payload excludes detail-only archived and pdfDownloadUrl. Verify the exact JSON and attached PDF bytes before acting on extracted fields.

Top-level patientName and patientDob reflect the current editable patient information in the web app. The nested aiResult retains the original extraction. Staff edits or clears can make the top-level values differ from the extraction or become null.

Illustrative payload with placeholder values:

JSON
{
  "fromNumber": "+14155550100",
  "toNumber": "+13125550123",
  "sendToken": "example-received-token",
  "callerName": null,
  "sentAt": "2026-10-07T12:00:00Z",
  "completedAt": "2026-10-07T12:01:00Z",
  "numPages": 2,
  "isTest": false,
  "faxStatus": "success",
  "errorDetails": null,
  "patientName": "Synthetic Q Patient",
  "patientDob": "1990-01-02",
  "aiResult": {
      "status": "successful",
      "skipReason": null,
      "completedAt": "2026-10-07T12:02:00Z",
      "documentTitle": "Synthetic Referral",
      "patientName": "Synthetic Q Patient",
      "patientFirstName": "Synthetic",
      "patientMiddleName": "Q",
      "patientLastName": "Patient",
      "patientDob": "1990-01-02",
      "patientGender": "Male",
      "patientPhoneNumber": "312-555-0199",
      "patientEmail": "synthetic@example.test",
      "patientAddress": "100 Synthetic Street",
      "patientCity": "Chicago",
      "patientState": "IL",
      "patientZipCode": "60601",
      "providerOffice": null,
      "practitionerName": null,
      "referringProvider": null,
      "primaryPlan": "Synthetic Plan",
      "primaryPlanName": "Synthetic Plan",
      "primaryMemberId": "MEM-1",
      "secondaryPlan": null,
      "secondaryPlanName": null,
      "secondaryMemberId": null,
      "documentSummary": "Synthetic referral for follow-up.",
      "dateOfService": null,
      "classification": null
    }
}
{
  "fromNumber": "+14155550100",
  "toNumber": "+13125550123",
  "sendToken": "example-received-token",
  "callerName": null,
  "sentAt": "2026-10-07T12:00:00Z",
  "completedAt": "2026-10-07T12:01:00Z",
  "numPages": 2,
  "isTest": false,
  "faxStatus": "success",
  "errorDetails": null,
  "patientName": "Synthetic Q Patient",
  "patientDob": "1990-01-02",
  "aiResult": {
      "status": "successful",
      "skipReason": null,
      "completedAt": "2026-10-07T12:02:00Z",
      "documentTitle": "Synthetic Referral",
      "patientName": "Synthetic Q Patient",
      "patientFirstName": "Synthetic",
      "patientMiddleName": "Q",
      "patientLastName": "Patient",
      "patientDob": "1990-01-02",
      "patientGender": "Male",
      "patientPhoneNumber": "312-555-0199",
      "patientEmail": "synthetic@example.test",
      "patientAddress": "100 Synthetic Street",
      "patientCity": "Chicago",
      "patientState": "IL",
      "patientZipCode": "60601",
      "providerOffice": null,
      "practitionerName": null,
      "referringProvider": null,
      "primaryPlan": "Synthetic Plan",
      "primaryPlanName": "Synthetic Plan",
      "primaryMemberId": "MEM-1",
      "secondaryPlan": null,
      "secondaryPlanName": null,
      "secondaryMemberId": null,
      "documentSummary": "Synthetic referral for follow-up.",
      "dateOfService": null,
      "classification": null
    }
}

Removing the organization link or losing production-access eligibility denies v3 requests and blocks pending integration callbacks. Unlinking does not cancel already accepted sends or restore an employee-based incoming callback signer. Coordinate access changes and recovery with Medsender.

Errors and existing integrations

  • 401: invalid/revoked credentials, test credentials on received-fax operations, missing enrollment, or missing active attribution member for writes. An ineligible test-key account receives 401 for sent-fax operations regardless of the production-access enforcement setting. An ineligible live-key account also receives 401 when production-access enforcement is disabled.
  • 403: when production-access enforcement is enabled, an ineligible live-key account is rejected with PRODUCTION_ACCESS_REQUIRED or BAA_REQUIRED.
  • 404: the fax does not exist within the linked organization.
  • 400: invalid sender number, upload, archive body, date/filter argument, sent sort or page size. Unknown list-query fields and unsupported create-body fields also return 400; for example, sent_status is not a supported list filter.

Error bodies vary by rejection path: 401 uses {"error":"Invalid credentials."}; 400 and 404 use an error object with status, title and detail. The eligibility 403 response includes a string error and the code above. Inspect the HTTP status and response shape rather than assuming a single error schema. Malformed JSON currently can return a non-JSON 500 response instead of a JSON 400.

V3 does not backfill v2 fax history, automatically migrate numbers or grant access through a shared parent or email match. Existing v2 sent, v2 received and other v2 APIs retain their contracts. The current OpenAPI description covers v2 and the v3 fax operations; use this guide for behavior and enrollment.