Faxes API reference

How is a fax sent?

POST /v1/faxes with a quote_id. The quote already holds the document, the destination, the sender and the price, so the send repeats none of them. Two optional fields ride along. approval_id is an approved request bound to this quote, and this one send consumes it. client_reference is your own label for the job.

The answer is the job, in state queued. Sending is asynchronous. The call returns as soon as the job is written, and the outcome arrives later on the job and as an event.

Why send an Idempotency-Key?

The summary of the operation recommends the Idempotency-Key header. A send that times out leaves you not knowing whether a job exists. Repeat the call with the same key and the answer is the same job, not a second fax. The list also filters by idempotency_key, so a client can look a job up by the key it used.

Which states can a job be in?

Six: queued, active, delivered, partial, failed and unknown. GET /v1/faxes/{fax_id} returns the state with pages_sent, attempt_count, captured_micro and, when the fax failed, a failure_code. A delivered job carries evidence, the carrier's report of the delivery.

delivered is said only with that evidence. unknown means no outcome was reported in time. A job in unknown or partial is never sent again by the service on its own. The errors page explains each state and what it means for the money held.

How do I follow one fax in detail?

Three reads. GET /v1/faxes/{fax_id}/attempts is the attempt history, one row per try. GET /v1/faxes/{fax_id}/events is the ordered list of events of this fax. GET /v1/faxes lists jobs newest first and filters by state.

For every fax at once, use webhooks, or walk the log in the events group.

Can a fax be cancelled?

POST /v1/faxes/{fax_id}/cancel cancels if that is still possible. A queued job is cancelled at once. Once sending has started the cancel is best effort, as the summary says: the carrier may already have the pages. A fax that has ended answers 409 not_cancelable. The call needs fax:cancel.

What is the receipt?

GET /v1/faxes/{fax_id}/receipt returns the delivery evidence as JSON once the fax has ended. It has the state, the numbers, pages_sent, the amount captured, the hash of the document and of the transmitted copy, the attempts and a note. GET /v1/faxes/{fax_id}/receipt.pdf is the same receipt as a one-page PDF, for a file or a person.

The receipt is the carrier's report, not legal proof of acceptance, and the PDF says so.

What can refuse a send?

A send answers 402 when the wallet cannot cover the quote. It answers 403 when a live API key has neither an approval nor a policy that allows the send. It answers 409 with quote_expired or quote_consumed when the quote can no longer be sent, and with an approval code when the approval does not match. A refused send creates no job.

Which scopes does the group use?

fax:send for the send, fax:cancel for the cancel and fax:read for every read, the receipt included. The default API key carries all three. A read-only API key keeps fax:read and drops the other two.

curl https://api.faxforagents.com/v1/faxes \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"quote_id":"quote_example"}'

curl https://api.faxforagents.com/v1/faxes/FAX_ID \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes/FAX_ID/attempts \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes/FAX_ID/cancel \
  -X POST \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes/FAX_ID/events \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes/FAX_ID/receipt \
  -H "Authorization: Bearer ffa_test_..."

curl https://api.faxforagents.com/v1/faxes/FAX_ID/receipt.pdf \
  -H "Authorization: Bearer ffa_test_..."