Send a fax
POST /api/fax: the fields, the two kinds of response, the limits, and the errors.
Endpoint
No authentication. Sendmultipart/form-data for files, or JSON when the document is inline Markdown or a cover page alone.
A complete fax
A request that includes a file, a letter as inlinemarkdown, or a cover page creates a draft. The response is 201 with id, url, and status_url. Give url to the person: it opens the preview with the price. If the person does not pay, the draft is abandoned after 4 hours.
documents[] one time for each file. The files are sent in the order you send them.
Use status_url to follow the fax. See Check the status.
When you write the document
Send the text as Markdown in themarkdown field. JSON is the simplest format for this:
\n. The response is the same as for a file. The text becomes the first document of the fax, a file named letter.md. Headings, lists, and tables are supported; raw HTML is printed as text.
A fax has no cover page unless you request one, so the letter must include its own names, date, and address block.
If the person must also add a file (a signed form, for example), send the letter and set file_expected=true. The form then opens with the letter attached.
Add a cover page
Setcover_page to true to put a cover page before the documents. The cover page shows the date, the fax number, the names you send, and cover_message.
To show the person’s email on the cover page, so the recipient can reply, set show_sender_email to true. By default the email is not shown. Like cover_message, it needs cover_page: true: without a cover page, the response is 422.
markdown letter, then the files.
A cover page can also be the whole fax: send cover_page and cover_message with no file and no letter.
A fax that still needs a file
When the person must add a file, send what you have and setfile_expected to true. A request with no file, no letter, and no cover page is handled the same way. The response is 200 with only url (no id, no status_url), and no fax exists yet.
url to the person. It opens the web form with what you sent. The person adds the file, checks the preview, and pays. The link expires after 24 hours.
Because this response has no status_url, you cannot poll the fax by yourself. After payment, the person’s confirmation page shows Track this fax with your AI assistant, with a prompt that contains the fax’s status address. Ask the person to copy that prompt to you; then read the status as described in Check the status.
Test numbers
To test your integration, send a fax to one of these numbers. The fax goes through the full flow: the preview, the price, the person’s click, and the status. It costs nothing, nothing is printed anywhere, and no email is sent.- The price is 0 in every currency. The link opens the preview and a “Send Fax” button. No card is asked for.
- The status is the same as for a real fax. A failed test fax has
failure.codeundeliverable; see When the fax could not be delivered. - A failed test fax can take a few minutes, because it is tried again first, as a real fax is. A delivered one is done in seconds.
- The
emailfield is still required, as for a real fax, but no email goes to it: no confirmation, no receipt, and no reminder. - Other numbers that start with
+99955501are reserved. The call refuses them with a422. - Test calls count toward the rate limits.
Rate limits
Create requests are limited per client IP address per hour. Invalid requests also count toward the limit. Each response reports the limit and the remaining requests in theX-RateLimit-Limit and X-RateLimit-Remaining headers. Over the limit, the response is 429. The status call has no hourly limit.
A site with many users: call from the browser
When your server makes the create request, all your users share the server’s IP address, and therefore its limit. Make the request from the user’s browser instead. The API accepts requests from any origin (CORS), so each request counts against the user’s own address.Currency
A complete fax is priced in the currency of the person’s country, which thecountry field sets. Without country, the price uses the country of the caller’s IP address. A request from the user’s browser gets the user’s country; a request from your server gets the server’s country, so pass country there. An unknown code is refused: UK is not a code; it is GB. A form link (file_expected) ignores country: the form takes the country from the person’s own browser.
For the prices in each currency, see Pricing & Payment.
Errors
Error responses are JSON.422 - validation error
422 - validation error
message and errors (the messages for each field). The messages say how to fix the request.429 - too many requests
429 - too many requests
message. Wait for the number of seconds in the Retry-After header, then try again. See Rate limits.OpenAPI
The full field reference and example responses are in the OpenAPI file.Related
Check the status
pending, delivered, failed, expiredPage for AI assistants
Body
Send JSON when the document is inline Markdown, or when the fax is
a cover page alone. Send multipart/form-data for files.
The document as inline Markdown text, when the agent wrote it.
UTF-8, not empty, at most 100 KB. It becomes the first document
of the fax, a file named letter.md. Headings, lists and tables
work; raw HTML is printed as text. Do not retype a person's file
as text.
"# Request for records\n\nDear Sir or Madam,\n\nPlease send me a copy of my records."
The person's country as a two-letter code (ISO 3166-1 alpha-2),
for the currency of the price and for the date format on the
cover page and in the emails. Without it, the country of the
caller's address is used. An unknown code is refused (UK is
not a code; it is GB). A link to the form ignores it: the
form takes the country from the person's browser.
2"DE"
Response
No fax is made yet: the person must add a file. The link opens the web form with what was sent.