A fax API turns a transmission from something a person does into something an application can request. That sounds unremarkable until you consider what it removes: the step where somebody prints a document, walks to a machine, dials a number from a form, and files a confirmation slip that nobody will ever read.
What a fax API is actually for
Two things, and they are worth separating because they justify the work differently.
The first is removing the person from a routine path. Where a system already holds the document and already knows the destination, having a human transcribe both into a machine is a source of delay and of error, and the error it produces most often is a wrong number.
The second is producing a record the calling system can use. A machine gave you a slip. An API gives the requesting application a job identity and a status it can store against the case, the record or the transaction that caused it. That is the difference between knowing a fax was sent and being able to show, later, which record it belonged to.
What the calling application supplies
Every fax API differs in detail, and all of them need broadly the same things.
- Credentials that identify the calling system, not a person.
- A destination, in a defined format, which is where most integration bugs live.
- The document, either inline or by reference.
- Optional metadata: a cover page, a reference of your own, a callback address for status.
The destination format deserves the attention it rarely gets. Numbers arrive from user input, from imported records and from other systems, in every shape people write them. Normalizing before submission, and rejecting what cannot be normalized, prevents a class of failure that is otherwise discovered by the person who was supposed to receive the document.
What comes back, and when
This is the part that most often surprises developers coming to fax for the first time: the useful answer does not arrive in the response.
Submitting a fax gets you an acknowledgment that the job was accepted and an identity for it. The transmission itself then takes anywhere from under a minute to a great deal longer, because the call has to be placed, answered and negotiated, and each page confirmed. If the destination is busy, retries stretch that out further. Sending a ten page document to a busy department can legitimately take an hour.
So the outcome arrives later, by one of two routes: a callback to an address you supplied, or a status endpoint you poll. Callbacks are more efficient and require you to be reachable; polling is simpler and needs a sensible interval. Most integrations end up doing both, because a callback that is missed should not mean a job whose fate is never learned.
Designing for the statuses that matter
A status vocabulary usually distinguishes accepted, in progress, delivered and failed, and the failures are where the design effort belongs. A busy destination, a number that does not answer, a machine that answered but was not a fax, and a rejection before the call was ever placed are four different events. Collapsing them into "failed" throws away exactly the information that determines what to do next, and the first three want automated retry while the fourth wants a person.
Authentication and access
An integration authenticates as a system, which changes how the credential has to be treated. It is long lived, it is not attached to anyone's employment, and it can send on behalf of the whole organization.
NIST SP 800-53 covers the ground here in its access control and Audit and Accountability families, and the practical implications are ordinary: keep the credential out of source control, scope it to what the integration needs, be able to rotate it without an outage, and make sure the transmission record identifies which system submitted. When a wrong document reaches a wrong destination, the question asked immediately afterwards is which system sent it and on whose behalf, and an integration that cannot answer becomes the suspect for everything.
What an API does not remove
It does not verify that the destination is correct. The API will send precisely where it is told, faster and more reliably than a person would, which means an integration that draws numbers from a poorly maintained field will misdeliver at scale rather than occasionally. Whatever validation existed when a human read the number off a form has to be rebuilt somewhere in the calling system.
It also does not make the far end more capable. The receiving machine still produces paper or an image, with no structure and no metadata, and anything downstream that needs the content still needs to extract it. An API improves the sending half of the exchange; the receiving half is unchanged, which is why fax remains a channel for delivering documents rather than exchanging data.
Where this fits with the rest
The API is one of several ways into the same service. Email suits a person deciding what to send. An inbound number suits documents arriving from outside. The API suits a system that already knows both the document and the destination, and the device path is the API with a connector in front of it. Our architecture page sets out how they relate.
Where to go next
For the mechanics of building the integration, see API-to-fax integration. For what actually happens on the call your API triggers, how electronic fax works. To discuss 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 points above.
- ITU-T Recommendation T.38. Procedures for real-time Group 3 facsimile communication over IP networks, the standard the transmission your API requests ultimately conforms to.