> ## Documentation Index
> Fetch the complete documentation index at: https://payperfax.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/agents) for the plain-language overview
and [payperfax.com/fax-api/](https://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.

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

## 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.

```bash theme={null}
curl https://fax.payperfax.com/api/fax \
  -F "to=+14155550101" \
  -F "email=person@example.com" \
  -F "documents[]=@letter.pdf"
```

```json theme={null}
{
  "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:

```bash theme={null}
curl https://fax.payperfax.com/api/fax \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155550101", "email": "person@example.com", "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.

```bash theme={null}
curl https://fax.payperfax.com/api/fax \
  -F "to=+14155550101" \
  -F "file_expected=true"
```

```json theme={null}
{
  "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.

<Warning>
  Do not retype a person's file as text. A typed copy of a signed form is not
  the form.
</Warning>

## 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.

<AccordionGroup>
  <Accordion title="422 - validation error" icon="triangle-exclamation">
    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.
  </Accordion>

  <Accordion title="429 - too many calls" icon="hourglass-half">
    Too many calls from one address in an hour. Wait for the number of
    seconds in the `Retry-After` header, then try again.
  </Accordion>

  <Accordion title="503 - new orders paused" icon="pause">
    New orders are paused for a short time. Try again later.
  </Accordion>
</AccordionGroup>

## OpenAPI

The full field reference and example answers are in the
[OpenAPI file](/api/payperfax-openapi.yaml).

## Related

<CardGroup cols={2}>
  <Card title="Check the status" icon="magnifying-glass" href="/api/check-status">
    Poll for `pending`, `delivered`, `failed`, `expired`
  </Card>

  <Card title="Page for AI assistants" icon="robot" href="/agents">
    The rules in plain language
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.