Send a fax

POST /api/fax: the fields, the two answers, and the errors.

The create call takes the fax fields and returns a link for the person. Nothing is sent and nothing is charged before the person opens the link, sees the preview with the price, and pays in the browser.

See the page for AI assistants for the plain-language overview and payperfax.com/fax-api/ for the main site.

Endpoint

POST https://fax.payperfax.com/api/fax

No authentication. Send multipart/form-data for files, or JSON when the document is inline Markdown or a cover page alone.

No account, no API key, no webhooks, no payment without a person. If a system needs those, this API is not the right fit.

A complete fax

A call that carries a file, a letter as inline markdown, or a cover page makes a draft and returns 201. The answer has id, url and status_url. Give url to the person: it opens the preview with the price. The draft is abandoned after 4 hours if the person does not pay.

curl https://fax.payperfax.com/api/fax \
  -F "to=[phone]" \
  -F "email=[e-mail]" \
  -F "documents[]=@letter.pdf"

{
  "id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "url": "https://fax.payperfax.com/fax/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/continue",
  "status_url": "https://fax.payperfax.com/api/fax/9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d/status"
}

When you write the document

Send the text as Markdown in the markdown field. JSON is the natural form:

curl https://fax.payperfax.com/api/fax \
  -H "Content-Type: application/json" \
  -d '{"to": "[phone]", "email": "[e-mail]", "markdown": "# Request for records\n\nDear Sir or Madam,\n\nPlease send me a copy of my records.\n\nJane Doe"}'

In JSON, write each line break of the text as \n. The answer 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 work. Raw HTML is printed as text.

A fax has no cover page unless you ask for one. So the letter must carry 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.

A fax that still needs a file

When the person must add a file, send what you have and set file_expected to true. A call with no file, no letter and no cover page is handled the same way. The answer is 200 with only url (no id, no status_url), and no fax exists yet.

curl https://fax.payperfax.com/api/fax \
  -F "to=[phone]" \
  -F "file_expected=true"

{
  "url": "https://fax.payperfax.com/fax/start/Jq3kV0c2mXb7RtY9pLs4HnW1eZa6UdG8fQi5oKjT"
}

Give url to the person. It opens the web form with what you sent, the person adds the file there, and then sees the preview and pays. The link is good for 24 hours.

Do not retype a person’s file as text. A typed copy of a signed form is not the form.

Fields

Field	Required	Description
to	Yes	The fax number in international format: +, the country code, the number
email	Yes*	The person’s email address. The confirmation and the receipt go there. Ask the person; do not guess. *Not required when the answer is a link to the form
documents[]	No	One or more files: PDF, DOC, DOCX, JPG, PNG, TIFF or Markdown (.md, 100 KB). At most 10 MB for all files together
markdown	No	The document as Markdown text, when you wrote it. It becomes the first document of the fax. At most 100 KB
file_expected	No	true when the person must still add a file. No fax is made yet: the answer is a link to the web form
cover_page	No	true adds a cover page. Default false. A fax can be a cover page alone
cover_message	No	Plain text for the cover page. It needs cover_page. Keep it short: a long message is cut off
sender_name	No	For the cover page
recipient_name	No	For the cover page
recipient_company	No	For the cover page
language	No	The language of the pages and emails: en, es, de, ja, ko, fr. Default en
timezone	No	An IANA time zone name, for the times in the emails. Example: America/New_York
country	No	The person’s country as a two-letter code (ISO 3166-1 alpha-2), for the currency of the price and the date format. Example: DE. Without it, the price uses the country of the caller’s address

Errors

Errors are JSON.

422 - validation error

A field is wrong, a field name is unknown, or the body is not valid JSON. The body has message and errors (the messages for each field). The messages say how to fix the call.

429 - too many calls

Too many calls from one address in an hour. Wait for the number of seconds in the Retry-After header, then try again.

503 - new orders paused

New orders are paused for a short time. Try again later.

OpenAPI

The full field reference and example answers are in the OpenAPI file.

Related

Check the status

Poll for pending, delivered, failed, expired

Page for AI assistants

The rules in plain language