This is the practical companion to the concepts: what an integration between an application and a fax service actually involves, in the order you will meet it, and which parts reward care.
The shape of it
An application holds a document and a destination. It authenticates to the service, submits both, receives a job identity, and learns the outcome later. Everything else is detail, but the detail is where integrations go wrong, and most of the wrongness is concentrated in two places: how destinations are handled, and what happens when a job does not succeed.
Authenticating
The integration authenticates as a system. Practically, that means a credential that is long lived, not attached to a person, and capable of sending on behalf of the organization.
- Keep it out of source control and out of the application's configuration files if your platform gives you somewhere better.
- Scope it to what the integration does.
- Be able to rotate it without downtime, which usually means supporting two valid credentials briefly.
- Make sure the transmission record identifies the submitting system, not just the organization.
NIST SP 800-53's access control and Audit and Accountability families are the reference for what these controls are for. The test to apply is a question: if a document reached a wrong destination six weeks ago, could you establish which system submitted it and on whose behalf? If not, the integration is not finished.
Submitting
Normalize the destination before you submit, and reject what will not normalize. Numbers arrive from user input, imports and other systems in every format people write them, and a service will faithfully dial whatever it is handed.
Decide early whether documents go inline or by reference. Inline is simpler and bounded by request size. By reference scales better for large documents and introduces a second thing that can fail, which the error handling then has to distinguish.
Send your own reference with the job. The service returns its identity, but the identity that matters to you is the case, record or transaction the fax belongs to, and carrying it through means the status that comes back can be filed without a lookup table.
Handling status
The outcome arrives later, so the integration has to be able to receive it later. That is the single largest difference from most APIs a developer will have used.
A callback is the efficient route and requires you to be reachable and to respond promptly. Polling is simpler and needs an interval that reflects reality: a fax to a busy destination can take a long time, and polling every few seconds achieves nothing but load.
Most durable integrations do both. The callback is the fast path, and a periodic sweep catches jobs whose callback never arrived. Without the sweep, a missed callback becomes a job in an eternal in-progress state, and those accumulate quietly until somebody asks why a queue is not draining.
Retries and doing it twice
The service retries the transmission. Your application should not, or not without care, because the failure modes are different.
A transmission that failed after several attempts to a busy number is a fax problem, and resubmitting it is reasonable. A submission that timed out before you received a job identity is an integration problem, and resubmitting it may send the document twice. That is not a theoretical concern: a duplicate on a fax is a second copy on somebody's desk, and for some record types it causes real confusion.
The remedy is to make submission idempotent, by sending a key you generate and the service honors, so that a retried submission is recognized rather than repeated. If the service does not support that, the calling system has to keep enough state to know whether it already sent, which is harder and worth avoiding.
Errors worth designing for
Four outcomes deserve distinct handling, and collapsing them is the most common design failure.
- Rejected at submission. A malformed destination or an unsupported document. Fix the input; retrying unchanged will fail identically.
- Busy or no answer. Ordinary and expected. Let the service retry; surface it only if it persists.
- Answered but not a fax. Usually a number that has been reassigned to a person. Worth flagging to somebody, because the record is now wrong.
- Transmission failure after connecting. A line or protocol problem. Retry is reasonable; a pattern of them against one destination is worth investigating.
What to log on your side
The service keeps its own record, and you should keep one too, because the two answer different questions. The service can tell you what happened to a transmission. Only your application can tell you why it was sent.
Store the job identity the service returns alongside your own reference, the destination as submitted after normalization, the submitting system, and each status you received with the time you received it. That is a small amount of data and it converts an awkward conversation into a lookup, which matters most on the day somebody asks about a document sent months ago by a process nobody remembers configuring.
Before you go live
Test against real destinations rather than a cooperative test number, with documents of realistic length, at the times of day you will actually send. Fax's failure modes are concentrated in exactly the conditions a friendly test avoids: long documents, busy departments, and imperfect lines.
Where to go next
For how LABUSA applies this pattern to copier and scanner workflows, see LABUSA API-to-fax.
For the concepts behind this, see electronic fax APIs explained. For how the API path relates to email, inbound and device submission, see the architecture page. To talk through a specific integration, tell us what you are working with, or see the feature overview.
Sources
- NIST SP 800-53 Rev. 5, Security and Privacy Controls for Information Systems and Organizations. The access control and Audit and Accountability families behind the credential and record guidance above.
- RFC 3362, Real-time Facsimile (T.38) image/t38 MIME Sub-type Registration. What the service produces from the document you submit.