How to Receive Faxes in Your Application

When a fax arrives, your application still needs to retrieve the document and get it to the right person or queue. That work should continue even if a notification arrives twice, a download fails, or a worker restarts.

With the Fax.Plus API, you can use an inbound notification to start processing, retrieve the fax record and file, and track the document through your own workflow. This guide walks through those steps and the recovery checks that keep received faxes from being overlooked.

Choose the receiving account and permissions

Start with the Fax.Plus number that will receive the documents and the user who owns its fax records. For a shared workflow, also decide who can access the document once it enters your application. A department number doesn't define those downstream permissions.

The Fax.Plus REST API requires Enterprise API access. Confirm your account's receiving setup and choose an authentication method. Keep credentials on the server. For a broader implementation brief, see Fax API Production Planning.

Check permissions for each operation. The fax record endpoint lists fax:fax:read or fax:all:read; the file endpoint lists fax:file:read or fax:all:read. Test against the endpoint-specific requirements. Access to a list of records alone doesn't establish access to their files.

Use self to retrieve the authenticated user's records. To retrieve another team member's faxes, check the account hierarchy: the team-member retrieval guide requires that member to be subordinate to the API user. Putting a member ID in a URL doesn't grant access.

Use a webhook to start processing

A webhook is an HTTP notification Fax.Plus sends to your application when a fax event occurs. For a new inbound integration, create an endpoint through POST /v3/webhooks with fax_received in filter_types. Enable webhooks in the account's Integrations settings and confirm that the account has the feature. Follow the endpoint creation reference for the required fields and permissions.

The webhook documentation defines fax_received as the completion of an inbound session. Use it to start checking and retrieving the fax. You still need to inspect the result to determine whether reception was complete.

Verify and save the notification

Verify the signature against the original request bytes and check its timestamp before trusting the payload. Obtain the endpoint-specific signing secret through Webhooks → Manage → Advanced → Signing Secret in the web app. The REST API does not return it, and web app webhook management requires an Owner or Admin. See the webhook Help guide.

Save a processing task in a database or persistent queue so it survives a restart. Then respond promptly and let a background worker retrieve the document. Return HTTP 200 after the task has been saved successfully.

Use the webhook-id HTTP header to recognize repeated deliveries. Make the duplicate check and save atomic, so simultaneous copies can't create two tasks. If a delivery is already safely recorded, return 200 without adding it again.

Protect the business action as well. Two different processing paths might discover the same fax, but they should not create two cases or attach the document twice. A unique key based on the authorized account and verified fax record ID can help. Keep this business key separate from the webhook delivery ID.

These storage and duplicate-handling patterns are recommendations for your application; you implement and test them.

Retrieve the fax record

Keep the account and fax identifiers from the notification and resolve them against the correct record. A session ID, record ID, and file field serve different purposes. In particular, don't substitute a filename for the fax ID required by a retrieval endpoint.

If you have the applicable record ID, use GET /v3/accounts/{user_id}/faxes/{fax_id}. The record reference describes the returned status, direction, owner, page count, and other metadata.

If the lookup doesn't resolve, check the account and identifier mapping or locate the record in the authorized inbox. Keep the task pending while you investigate rather than dropping the notification.

List received records when needed

Use GET /v3/accounts/{user_id}/faxes?category=inbox to list received faxes. The following examples use a Personal Access Token (PAT). They illustrate request structure and have not been executed or tested end to end.

Set FAX_PLUS_TOKEN securely in your environment. This request retrieves the first page:

curl --fail-with-body --get \
 'https://restapi.fax.plus/v3/accounts/self/faxes' \
 -H "Authorization: Bearer $FAX_PLUS_TOKEN" \
 -H 'Accept: application/json' \
 --data-urlencode 'category=inbox' \
 --data-urlencode 'limit=50' \
 --data-urlencode 'offset=0'

OAuth requests also require the x-fax-clientid header shown in the listing reference. Follow the requirements for your chosen authentication method.

Check for partial reception

Inspect the status before starting normal downstream processing. A partially_received result means only part of the transmission arrived. Put it in a review queue, retain the available evidence under your policy, and give staff an approved way to request the missing document. The fax status definitions explain the results.

Page count is useful, but it doesn't prove the sender included every intended page. If your workflow expects a cover sheet and three attachments, application-level or human checks still need to establish that all required documents are present.

Download and store the file privately

Once you've identified the correct fax record, retrieve its file through GET /v3/accounts/{user_id}/files/{fax_id}. Request a PDF with Accept: application/pdf. The download reference also documents TIFF and marks the older format parameter as deprecated in favor of the Accept header.

Set FAX_ID to the verified fax record ID:

curl --fail-with-body \
 "https://restapi.fax.plus/v3/accounts/self/files/$FAX_ID" \
 -H "Authorization: Bearer $FAX_PLUS_TOKEN" \
 -H 'Accept: application/pdf' \
 --output received-fax.download

Use the authorized member ID instead of self when that member is the verified owner. This snippet shows the request, not a complete production downloader.

Before treating the response as a PDF, check the HTTP result and response type. An error response must not become an attachment just because its local filename ends in .pdf. Download to temporary private storage, apply your file validation and malware-screening policy, and move the document to its final location only after those checks succeed.

Use a server-generated storage name. Don't let an inbound filename determine a filesystem path or public URL. Restrict access to authorized users and services, and keep credentials and fax contents out of routine logs.

Mark the document as stored only after the write has completed reliably. If storage fails, leave the task pending for a controlled retry. Track receipt, download, storage, and application handoff separately so you can see where processing stopped.

Route the document to the right place

Use routing information you control. A receiving number may identify a department, while a verified reference on the document may identify a case. Your application's authorization rules should determine who can open the resulting record.

Treat the sender's fax number as context, not sufficient proof of identity or the right customer record. If several records could match, send the document for review.

For example, a service application could send documents received on its maintenance number to an intake queue. An operator confirms the work-order reference, then the application links the file and records who approved the match. This is an illustrative workflow you build in your application.

The same responsibility applies to healthcare. Receiving a fax doesn't automatically match it to a patient, update an EHR, or satisfy your organization's compliance obligations. Such workflows need their own validated mapping, permissions, agreements, and operational review.

Give staff clear statuses such as “Download pending,” “Ready for review,” and “Attached to case.” Include a reason and an owner for stalled items, so the next action is clear.

Recover missed events and interrupted work

Add a periodic process that lists inbox records and compares them with the faxes your application has handled. This reconciliation gives you a recovery path if the receiver is unavailable or a worker stops between steps.

Read every page of results

The listing documentation limits each response to 50 records. Results are in data.records, and there is no has_more flag.

For a fixed query, increase offset by the number of records returned. Continue until a page contains fewer records than the requested limit. Narrower time windows can reduce the result set, but they cannot separate more than 50 records that share the same timestamp.

Avoid gaps between time windows

The after and before filters use UTC and exclude their exact boundary seconds. Use fixed, overlapping windows and deduplicate records you have already handled.

Advance your recovery checkpoint only after the whole window has been processed successfully. Recheck recent windows for records that become visible later, and test the approach at your expected volume.

The ordinary inbox listing excludes deleted records and user-marked spam. Account for those limits in your retention and recovery rules; the inbox is not an unrestricted archive.

Retry temporary read or storage failures with a bounded delay and alert someone after repeated failures. Investigate permission errors separately. Also keep your own processing record: the user's read/unread flag in the web app doesn't tell you whether application intake finished.

Test the complete receiving workflow

Use controlled documents without real sensitive information for initial tests. Check that:

• A complete fax becomes one stored document in the correct queue.
• A partial fax is flagged for review.
• Duplicate events and reconciliation don't create duplicate attachments.
• Failed downloads and worker restarts resume without losing the task.
• Insufficient permissions prevent access to another member's documents.
• Ambiguous matches wait for review.
• Pagination and time boundaries don't skip records.

These are proposed acceptance tests for your implementation, not results from a tested integration.

Start with one receiving workflow

Choose one receiving number and one application queue. Verify that an authorized fax can move from receipt to record retrieval, private storage, and a recorded handoff. Then interrupt the process and check that it resumes without duplicate work before expanding the workflow.

‍