Sent 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 sent 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.
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 path | Result |
|---|---|
| POST /sent_faxes | Upload a file and send; 201 with faxId. |
| GET /sent_faxes | Organization sent deliveries in sentFaxes plus pagination meta. |
| GET /sent_faxes/:id | Top-level fax details/status and secureLink. |
Simulated sends with test keys
Already-enrolled accounts can use a sk_test_ key for sent-fax uploads, listing, polling and downloads. All operations require a confirmed, active account, BAA coverage and an organization link, as with live keys. Sent-fax uploads additionally require an active attribution member and an active organization sender number. Use an approved sample document: it is stored in the linked organization.
A test send completes asynchronously as simulated success without carrier delivery, delivery to another Medsender inbox, EMR upload, transmission charges or use of the self-serve live spend cap. Set the optional test_outcome=failure form field to exercise a failed completion; success is the default. This field returns 400 with live credentials or any other value.
Poll the returned faxId with the same test key. Test responses and callbacks carry isTest=true. Sent lists and downloads are separated by the credential: test keys access test faxes, live keys access live faxes, and a token from the other mode returns 404. The is_test query filter remains unsupported.
Configure the portal test webhook secret and the sender number’s callback URL. The existing form-encoded recordDetails callback uses the test signing credentials and can be delivered more than once. Received-fax reads, downloads and archiving require live credentials; test keys receive 401. Signup alone does not enable these enrolled test sends.
Send a fax
Send multipart fields file, from_number and to_number. Optional fields include document_title, patient_name, patient_dob (YYYY-MM-DD), recipient_name, note. The cover sheet uses the configured organization, department or fax-number sender identity; a per-send sender_name does not override it. Use document_type=document_only to omit the cover sheet; the default includes both the document and a cover sheet. Salesforce file selection is outside v3.
HTTP 201 means the send was accepted, not that delivery completed. Save faxId and use it for polling. A repeated POST can send another fax; do not blindly retry after a timeout with an unknown outcome. Reconcile the sent list or contact support first.
Poll and download a sent fax
Poll sentStatus to follow a send. inprogress means transmission is pending. A failure can describe a failed attempt while automatic retries remain; it can return to inprogress and later reach success. Inspect errorDetails, but do not send another fax based on a polled failure alone.
For sends created through v3, use the terminal callback to reconcile the delivery outcome. If it has not arrived, the outcome is still uncertain: callback delivery may be delayed or blocked by access or configuration changes. Reconcile with Medsender before repeating the POST. This response excerpt shows a completed transmission:
On failure, errorDetails is an object, not a string:
Detail also includes compatibility fields: recordStatus is activated, documentType is both even for a document-only send, and expiry, viewCount and senderName are retained. senderName can be null and is not the cover-sheet display name. For fax deliveries, destinations in toNumber use E.164, for example +13125550123; fromNumber also uses E.164.
Fetch the returned secureLink directly to download the PDF. It expires after five minutes; request detail again for a fresh link. Treat signed URLs as credentials. The selected sender document is used for downloads and patient filters. Where a preserved sender copy exists it is preferred; otherwise the current record is used. numPages counts transmitted pages, including any cover sheet, and can differ from the downloaded document.
List and filter faxes
Sent filters: from_number, to_number, recipient_name, patient_name, patient_dob, date_start and date_end. Use sort=date or sort=dob, with sort_dir=asc or desc. Unsupported sender_name, record_status and is_test filters return 400, even if blank or false.
With live credentials, the sent list includes eligible document deliveries in the linked organization with isTest=false, including secure-email deliveries. Test credentials select isTest=true instead. toNumber and sentStatus can be null for an email delivery. Status values can include scheduled and resent as well as inprogress, success and failure; do not assume every row is a completed fax or was created through v3.
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.
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.
Sent callbacks are form-encoded POSTs with a recordDetails field containing a serialized JSON object. They carry the sent-detail fields plus secureLink. On failure, both the callback and API JSON use nested errorDetails.errorMessage.
Illustrative payload with placeholder values:
Failure callback excerpt:
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_REQUIREDorBAA_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_statusis 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.