Agent fax lines

Agent fax lines are in limited rollout. Interchange provisions each line with the customer and enables the account before the fax API becomes available. There is not yet a self-service number picker.

An agent fax line gives a storefront agent a real telephone number for inbound and outbound PDF fax delivery. It is useful for partners whose existing workflows still produce paper or fax documents.

How inbound fax works

When the assigned number receives a fax, Interchange:

verifies the carrier-signed event and copies the PDF into private storage;
verifies the stored file and extracts bounded document text;
treats that text as untrusted external input to the assigned storefront agent; and
renders the agent’s response as a PDF and sends it back to the verified originating fax number.

Interchange does not store the carrier’s temporary media URL or expose it to the agent. Fax files are isolated by customer and expire under the fax storage retention policy. Delivery metadata and content digests remain available for idempotency and audit without retaining telephone numbers in the command ledger.

Provision a line

Contact Interchange to request a line during the limited rollout. Choose the customer account, storefront agent, country or region, and preferred area code. Interchange assigns the carrier number, verifies that it belongs to the fax application, and activates its route to the selected agent. Provisioning is currently an operator action. API keys cannot create or move a line, and entering an arbitrary existing number does not claim it. Bring-your- own-number porting and a self-service distribution card are planned separately.

Send a fax

Send an outbound PDF with POST /api/v2/communications/faxes. The caller needs interchange:write, access to the endpoint’s customer, and enrollment in the limited rollout.

curl -X POST "https://api.interchange.io/api/v2/communications/faxes" \
  -H "Authorization: Bearer $INTERCHANGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "df3b1f38-77ad-4e2e-ad67-594433cf1be7",
    "endpointId": "123",
    "to": "+12025550101",
    "mediaUrl": "https://relay.example.com/fax.pdf",
    "mediaSha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  }'

Field	Required	Description
`requestId`	Yes	A UUID owned by the caller. Reuse it only to retry the same intended fax.
`endpointId`	Yes	The Interchange fax-line ID, represented as a numeric string.
`to`	Yes	Destination telephone number in E.164 format.
`mediaUrl`	Yes	Temporary HTTPS URL from which the carrier can fetch the PDF. Embedded credentials are rejected.
`mediaSha256`	Yes	Lowercase SHA-256 digest of the PDF at `mediaUrl`.

The URL must remain reachable long enough for carrier ingestion. Use a short expiry and do not require cookies, interactive login, or request headers that the carrier cannot provide. An accepted request returns HTTP 202:

{
  "data": {
    "fax": {
      "providerFaxId": "b4c7f7e8-33c4-4af6-82f4-55a41ba93427",
      "providerStatus": "queued",
      "duplicate": false
    }
  },
  "error": null
}

queued confirms carrier acceptance, not final delivery to the remote fax machine. duplicate is true when Interchange returns the result of an earlier completed request with the same requestId.

Retry and error behavior

Interchange binds requestId to the endpoint, destination, and PDF digest. Repeating that exact command is safe. Reusing the UUID with different input returns 409.

Status	Meaning	Action
`400`	A field is invalid, the number is not E.164, or the media URL is not HTTPS.	Correct the request.
`401` or `403`	The credential is missing, invalid, or lacks `interchange:write`.	Correct the credential or permission.
`404`	The rollout is disabled or the fax line is not active for this customer.	Ask Interchange to verify enrollment and provisioning.
`409`	The request UUID was reused with different immutable input, or an earlier submission is unresolved.	Keep the original input or use a new UUID only for a genuinely new fax.
`503` with `submission_unknown`	The carrier may have accepted the request, but Interchange did not receive a definitive result.	Do not submit the same fax under a new UUID; ask Interchange to reconcile it.

Interchange never automatically repeats an ambiguous carrier submission. This prevents a network timeout from producing two physical faxes.

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Agent fax lines

Agent fax lines

How inbound fax works

Provision a line

Send a fax

Retry and error behavior

​Agent fax lines

​How inbound fax works

​Provision a line

​Send a fax

​Retry and error behavior

Agent fax lines

How inbound fax works

Provision a line

Send a fax

Retry and error behavior