Skip to main content
The create call takes the fax fields and returns a link for the person. Nothing is sent and nothing is charged until the person opens the link, checks the preview with the price, and pays in the browser. See the page for AI assistants for the plain-language overview and payperfax.com/pay-per-fax-api/ for the main site.

Endpoint

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 request that includes a file, a letter as inline markdown, 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.
Send 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 the markdown field. JSON is the simplest format for this:
In JSON, write each line break as \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

Set cover_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.
The order of the pages is: the cover page, then the 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 set file_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.
Give 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.
Do not retype a person’s file as text. A typed copy of a signed form is not the form.

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.code undeliverable; 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 email field 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 +99955501 are reserved. The call refuses them with a 422.
  • 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 the X-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 the country 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.
A field is invalid, 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 request.
Too many create requests from one address in an hour. The body has message. Wait for the number of seconds in the Retry-After header, then try again. See Rate limits.
New orders are paused for a short time (Retry-After: 3600), or the service is briefly unavailable (Retry-After: 5). Wait for the number of seconds in the Retry-After header, then try again.

OpenAPI

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

Check the status

Poll for pending, delivered, failed, expired

Page for AI assistants

The rules in plain language

Body

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

to
string
required

The fax number in international format: +, the country code, the number. To test, use a test number: +9995550100 (delivered), +9995550101 (busy) or +9995550102 (number not in use). A test fax costs nothing and sends no email.

Example:

"+14155550101"

email
string<email>

The person's email address. The confirmation and the receipt go there. Ask the person; do not guess. Required when a draft is made; optional when the response is a link to the form. The domain is checked in DNS.

Example:

"person@example.com"

documents[]
file[]

The files of the fax, in the order they are sent: PDF, DOC, DOCX, JPG, PNG, TIFF or Markdown (.md, 100 KB). At most 10 MB for all files together; the inline markdown text counts. Without a file, a letter or a cover page, the response is a link to the form.

markdown
string

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.

Example:

"# Request for records\n\nDear Sir or Madam,\n\nPlease send me a copy of my records."

file_expected
boolean
default:false

true when the person must still add a file. No fax is made yet: the response is a link to the web form, with what was sent.

cover_page
boolean
default:false

Adds a cover page before the documents.

cover_message
string

Plain text for the cover page. Line breaks are kept. Keep it short: a long message is cut off. It needs cover_page: true: without a cover page the call is refused, so no message is lost.

Maximum string length: 5000
show_sender_email
boolean
default:false

true shows the person's email on the cover page, so the recipient can reply. It needs cover_page: true: without a cover page the call is refused.

sender_name
string

For the cover page.

Maximum string length: 100
recipient_name
string

For the cover page.

Maximum string length: 100
recipient_company
string

For the cover page.

Maximum string length: 100
language
enum<string>
default:en

The language of the pages and emails for the person.

Available options:
en,
es,
de,
ja,
ko,
fr,
it
timezone
string

An IANA time zone name, for the times in the emails. An unknown name is refused. Without it, times are in UTC.

Example:

"America/New_York"

country
string

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.

Required string length: 2
Example:

"DE"

Response

No fax is made yet: the person must add a file. The link opens the web form with what was sent.

url
string<uri>
required

The link for the person: the web form, with what was sent. The person adds the file there. Good for 24 hours.

Example:

"https://fax.payperfax.com/fax/start/Jq3kV0c2mXb7RtY9pLs4HnW1eZa6UdG8fQi5oKjT"