AFAX API V4

Secure, API-driven fax communications for application and workflow integration

UAT Environment
This documentation describes the AFAX API V4 User Acceptance Testing environment.
The API is under active validation and should not be used for production workloads or production-sensitive data.

Welcome to AFAX API V4

AFAX API V4 provides a secure REST API for integrating fax communications directly into applications, platforms, and automated business workflows.

The API supports:

OAuth 2.0 client authentication

Outbound fax submission

Multiple-recipient fax transmission

URL, Base64, and binary document submission

Fax status and result retrieval

Fax activity listing and filtering

Fax media retrieval

Fax cancellation and deletion where permitted

Persistent webhook subscriptions

Signed real-time fax event notifications

Inbound fax notifications

AFAX API V4 is asynchronous by design. Applications submit work to AFAX and receive an AFAX fax identifier (rfid) that can be used for subsequent operations.

For event-driven integrations, persistent webhooks are recommended instead of frequent status polling.

UAT Base URLs

Resource API

https://api.faxlink.ca/afx/v4

OAuth Token Service

Use the OAuth token endpoint provided for your UAT account to obtain an access token before calling protected API resources.

Production API hostnames and credentials will be provided separately when an integration is approved for production use.

All AFAX API communication requires HTTPS.

Quick Start

A typical AFAX integration follows this sequence:

Obtain OAuth Access Token
        ↓
Submit Fax + Idempotency-Key
        ↓
Store returned RFID
        ↓
Receive asynchronous processing
        ↓
Webhook events and/or GET fax status
        ↓
Retrieve final result or fax media

For a basic UAT integration, we recommend testing in this order:

Obtain an OAuth access token.

Send a test fax.

Store the returned rfid.

Retrieve the fax using the RFID.

List fax activity.

Retrieve available fax media.

Create a persistent webhook.

Verify signed webhook delivery.

Test inbound fax.received delivery if inbound faxing is enabled for your account.

Authentication

AFAX API V4 uses the OAuth 2.0 Client Credentials flow for application-to-application authentication.

Your AFAX API account is issued credentials that identify and authenticate your application.

Request an access token using:

Example request:

grant_type=client_credentials
&client_id=<your-client-id>
&client_secret=<your-client-secret>
&scope=fax.send fax.read

A successful response contains a Bearer access token.

Use it on subsequent API requests:

Access tokens currently have a one-hour lifetime.

Applications should cache and reuse the access token until it approaches expiration rather than requesting a new token for every API operation.

API Scopes

Access is capability-controlled. The scopes available to a client depend on the AFAX services enabled for its account.

Examples include:

Scope	Purpose
`fax.send`	Submit outbound faxes
`fax.read`	Retrieve fax information
`fax.download`	Retrieve fax media
`webhooks.manage`	Manage webhook subscriptions
`reports.read`	Access reporting resources
`numbers.read`	Access authorized number information

Request only the scopes required by your application.

Sending a Fax

AFAX currently supports three submission modes:

URL documents

Use POST /faxes to submit documents that AFAX can securely retrieve from supplied URLs.

Multiple URL documents may be submitted in a single fax request.

Base64 document

Use POST /faxes to submit a Base64-encoded document directly within the request.

The Base64 submission mode currently supports one document per fax request.

Binary document

Use POST /faxes/binary to submit a raw binary document.

The binary submission mode currently supports one document per fax request.

Supported Document Types

The current UAT release supports:

Document	MIME Type
PDF	`application/pdf`
TIFF	`image/tiff`
Microsoft Word `.doc`	`application/msword`
Microsoft Word `.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`

AFAX validates submitted documents rather than relying solely on the supplied filename or MIME type.

Document type, file-size and document-count limits may vary according to the policy configured for your AFAX account.

Preventing Duplicate Faxes

Every fax submission requires an:

For example:

The Idempotency-Key identifies one logical fax submission.

Generate a new unique key for every new fax.

If the outcome of a request is uncertain because of a network timeout, connection interruption, or similar communication failure, retry the same fax using the same key.

New Fax
   ↓
Generate Key A
   ↓
POST /faxes
   ↓
Network timeout / uncertain response
   ↓
Retry SAME request with Key A
   ↓
AFAX returns the original acceptance
   ↓
No duplicate fax is created

AFAX retains the idempotency association for 24 hours.

During that period:

Same key + same request → original accepted fax is returned.

Same key + different request → 409 Conflict.

A different key represents a new fax submission.

The maximum Idempotency-Key length is 200 characters.

Important: Do not generate a new idempotency key simply because the original HTTP request timed out. Reuse the original key when retrying the same logical fax.

AFAX Fax Identifier

An accepted fax receives a public AFAX fax identifier called an rfid.

Example:

AFX591DF63428724AF7B89E9B0E3DA09567

The identifier format is:

AFX + 32 hexadecimal characters

Store the RFID in your application.

It is used for subsequent operations such as:

and applicable fax lifecycle operations.

The RFID is tenant-scoped. An authenticated client cannot use an RFID to access another AFAX customer's fax.

Fax Status and Activity

Retrieve an individual fax using:

AFAX provides normalized public fax states rather than exposing internal fax-processing implementation details.

Fax information may include:

RFID

Current status

Client reference

Sender and recipient information

Document/page information

Retry information

Processing timestamps

Transmission duration

Far-end information when available

Result or failure information

Use:

to retrieve fax activity using pagination and supported filters.

The endpoint uses page-based pagination and returns metadata such as:

{
  "page": 1,
  "pageSize": 25,
  "total": 142
}

Refer to the endpoint documentation for supported filters and allowed status values.

Fax Media

Authorized applications can retrieve available fax content using:

Fax media may contain confidential or sensitive information.

Applications consuming fax documents are responsible for applying appropriate access controls, secure storage, retention policies, and privacy safeguards appropriate to their use case.

Webhooks

AFAX webhooks provide asynchronous notifications when fax lifecycle events occur.

Persistent webhook subscriptions are recommended for applications that need real-time fax status or inbound fax notifications.

Depending on the subscribed event set, notifications can include events such as:

fax.accepted
fax.queued
fax.processing
fax.completed
fax.failed
fax.received
fax.cancelled
fax.deleted

Refer to the Webhook API reference for the authoritative event list supported by the current release.

Webhook subscriptions can be created, listed, updated, deleted, and have their signing secret rotated.

Webhook Security

Persistent AFAX webhook deliveries are authenticated using HMAC-SHA256.

When a webhook secret is created or rotated, AFAX provides a signing secret in the form:

whsec_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Treat this value as a credential.

Do not expose it in browser code, public repositories, logs, screenshots, or documentation.

Signature Headers

A signed AFAX webhook includes headers similar to:

Signature Construction

AFAX constructs the signing input exactly as:

<X-AFAX-Timestamp>.<X-AFAX-Delivery-ID>.<raw-request-body>

For example:

2026-09-15T12:34:56.789Z.12345.{"rfid":"AFX0123456789ABCDEF0123456789ABCDEF","status":"sent"}

AFAX then calculates:

HMAC-SHA256(
    UTF8(webhook_secret),
    UTF8(signing_input)
)

The resulting 32-byte digest is encoded as 64 lowercase hexadecimal characters and sent as:

Raw Body Requirement

Signature verification must use the exact raw HTTP request body received from AFAX.

Do not:

Parse and reserialize the JSON before verification.

Pretty-print the JSON.

Change whitespace.

Reorder JSON properties.

Normalize escaping.

Add a trailing newline.

Any byte-level change produces a different signature.

The recommended receiver flow is:

Receive HTTPS POST
        ↓
Preserve raw request body
        ↓
Read AFAX signature headers
        ↓
Construct signing input
        ↓
Calculate HMAC-SHA256
        ↓
Compare signature
        ↓
Validate timestamp freshness
        ↓
Parse JSON
        ↓
Process event

Always verify the signature before trusting or processing the webhook payload.

Webhook consumers should also be idempotent because delivery may be retried.

Inbound Fax Notifications

Accounts with authorized inbound fax numbers and an enabled persistent webhook subscription can receive inbound fax notifications.

A received fax can generate:

fax.received

The notification provides the fax metadata required to identify the fax.

Applications can subsequently retrieve authorized fax information and available media through the API.

The webhook payload itself should not be treated as a replacement for retrieving the authoritative fax resource when the complete current fax state is required.

HTTP Response Codes

AFAX uses standard HTTP status codes.

Status	Meaning
`200`	Request completed successfully
`201`	Resource created
`202`	Request accepted for asynchronous processing
`400`	Invalid or incomplete request
`401`	Authentication failed or is required
`403`	Authenticated client is not authorized for the operation
`404`	Resource not found
`409`	Resource or idempotency conflict
`429`	Request rate limit exceeded
`500`	Unexpected server-side error

Applications should use structured error codes and HTTP status values for program logic rather than depending solely on human-readable error descriptions.

Integration Best Practices

Cache OAuth tokens

Reuse an access token until it approaches expiration.

Use idempotency on every fax submission

Generate one key for each logical fax and reuse it when retrying that same fax.

Store the RFID

Keep the returned AFAX RFID as your reference for subsequent fax operations.

Prefer webhooks over frequent polling

Use persistent webhook subscriptions for asynchronous lifecycle notifications.

Verify every signed webhook

Validate the HMAC signature using the raw request body before processing the event.

Validate webhook timestamps

Reject webhook requests whose timestamps fall outside the acceptable time window defined by your application's security policy.

Handle webhook retries safely

Design webhook processing to tolerate receiving the same logical delivery more than once.

Protect credentials

OAuth client secrets, Bearer tokens, and whsec_ webhook signing secrets must be treated as credentials.

Protect fax content

Fax documents and metadata may contain confidential or sensitive information. Apply appropriate security, privacy, retention, and access-control policies.

UAT Testing Checklist

Before requesting production access, validate at minimum:

OAuth client-credentials authentication

Required API scopes

URL document fax submission

Base64 document fax submission if applicable

Binary fax submission if applicable

Multiple-recipient submission if applicable

Idempotency-Key duplicate protection

Fax status retrieval

Fax listing and pagination

Fax media retrieval

Persistent webhook creation

Webhook HMAC-SHA256 verification

Webhook retry handling

Webhook secret rotation

Inbound fax.received notification if applicable

Fax cancellation/deletion if used by your integration

Error and timeout handling

Next Steps

Use the API reference to explore the individual AFAX API V4 endpoints and their complete request and response schemas.

A recommended first integration is:

Authenticate → Send Fax → Retrieve Fax → Configure Webhook → Verify Signature

Production credentials and production service information should be kept separate from the UAT environment.

AFAX™ — Secure Digital Fax Communications

Documents

AFAX API V4#

Welcome to AFAX API V4#

UAT Base URLs#

Resource API#

OAuth Token Service#

Quick Start#

Authentication#

API Scopes#

Sending a Fax#

URL documents#

Base64 document#

Binary document#

Supported Document Types#

Preventing Duplicate Faxes#

AFAX Fax Identifier#

Fax Status and Activity#

Fax Media#

Webhooks#

Webhook Security#

Signature Headers#

Signature Construction#

Raw Body Requirement#

Inbound Fax Notifications#

HTTP Response Codes#

Integration Best Practices#

Cache OAuth tokens#

Use idempotency on every fax submission#

Store the RFID#

Prefer webhooks over frequent polling#

Verify every signed webhook#

Validate webhook timestamps#

Handle webhook retries safely#

Protect credentials#

Protect fax content#

UAT Testing Checklist#

Next Steps#