Fax quotes API reference

Why does a send start with a quote?

Because the quote is what gets approved and what gets charged. POST /v1/fax-quotes takes a document and a destination and answers with the price before anything is sent. The send in the faxes group then names the quote and nothing else about the fax. Whatever the quote fixed is what goes out.

A quote costs nothing and sends nothing. An agent can quote, show the amount to a person and stop there.

What goes into a quote?

Two required fields. document_id names the document and to is the destination in E.164, for example +12025550123.

The optional fields shape the fax. from is a number you own. Leave it out and the fax goes out from the shared pool. cover adds a cover sheet with to_name, from_name, subject and message. sender_name is the name that identifies the sender, and the carrier gets it as the caller name for its header line. delete_after_send deletes the document and the transmitted copy the moment the fax ends in delivered, partial or failed.

quality sets the resolution. The schema lists four words. standard is the fax standard's 204 by 98 dpi. fine is 204 by 196 and the default. superfine and ultra are finer still. The send guide has the measurement behind the last two and which one suits small print.

What does the answer fix?

The route and its label, document_pages, cover_pages and billable_pages, the amount in amount_micro with the currency, and per_page_micro. price_version names the rate table the price came from. document_sha256 is the hash of the document at the moment of the quote.

Two fields tell an agent what comes next. authorization_required is true when a live send of this quote needs a person's approval, because no policy allows it. warnings lists the service's warnings for this quote.

A destination outside the published routes is refused. The quote does not exist then, and neither can a send.

How long is a quote good for?

Until expires_at. GET /v1/fax-quotes/{quote_id} reads a quote again, and expired says whether its time has passed. An expired quote cannot be sent. Quote again, and if a person had approved the old one, ask again too: an approval is bound to its quote and expires with it. The limits page has the life of a quote as a value.

A quote is used once. After a send, consumed_by_job_id names the fax that used it. A second send needs a second quote, even for the same document and number.

What can change between the quote and the send?

Nothing that matters. The document is immutable, so the hash on the quote is the hash that is sent. The price comes from the quote, not from the rate table of a later minute.

That is the reason the API splits one action in two. The approval request in the approvals group copies the quote. A person who approves sees the same pages, number and amount that the send will use.

Which scope does a quote need?

fax:quote, for the create and the read. The default API key carries it. A key that may quote and may not send lets an agent prepare a fax and leave the sending to someone else.

curl https://api.faxforagents.com/v1/fax-quotes \
  -X POST \
  -H "Authorization: Bearer ffa_test_..." \
  -H "Content-Type: application/json" \
  -d '{"document_id":"document_example","to":"+15550000001"}'

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