# Send a fax

Send a PDF to a fax number from your account. The call returns as soon as the carrier accepts the fax; poll the receipt for delivery. Billed per transmitted page at delivery; a fax that fails is not charged.

## Send a fax

```
POST /fax
```

Authentication: Bearer API key required.

Multipart (`to` + one or more PDF `files`, sent as one fax) or JSON (`to` plus exactly one of `job_id`, `form_id`, `pdf_url`, `pdf_base64`). Returns 202 with a job id while the fax transmits. A deduplicated: true key appears only when the same packet to the same number was sent moments ago: the earlier job comes back instead of a second fax.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| to | body | string (E.164) | yes | Destination fax number, for example +15025551212. United States, Canada, and Mexico are served. |
| files | body | file (multipart), repeatable | yes | One or more PDFs, sent in order as a single fax. |
| job_id | body | uuid | no | A ready context-fill or commit job; its filled PDF is faxed (JSON body). |
| form_id | body | uuid | no | A ready form; its fillable PDF is faxed (JSON body). |
| pdf_url | body | string (url) | no | A public https link to the PDF (JSON body). |
| pdf_base64 | body | string (base64) | no | Base64-encoded PDF bytes (JSON body). |
| artifact_id | body | string | no | The artifact_id of a file Emboss already made or received, such as a job's filled PDF or a form's fillable PDF (JSON body). See Artifacts and lineage. |
| artifact_token | body | string | no | Optional, with artifact_id: the artifact_token returned next to an artifact made on the pay-per-call API, so your account can fax a file it did not make (JSON body). POST /fax itself always needs your API key. |
| sources | body | array | no | Up to twenty entries of artifact_id, artifact_token, pages, faxed as one packet in order (JSON body). Exactly one of sources, artifact_id, job_id, form_id, pdf_url, pdf_base64. See Artifacts and lineage for the page-selection grammar. |
| Idempotency-Key | header | string | no | Optional, recommended. Retrying with the same key answers 200 with the original fax job, so a retry never sends the fax twice. Scoped to your account, valid 24 hours, and shared by every call on the account, so use a fresh key for each fax. |

```curl
curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer sk_..." \
  -F "to=+15025551212" \
  -F "files=@./notice.pdf"

curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "job_id": "<job id from the commit>"}'

curl -X POST https://api.getemboss.ai/fax \
  -H "Authorization: Bearer sk_..." \
  -H "Content-Type: application/json" \
  -d '{"to": "+15025551212", "sources": [
        {"artifact_id": "<package>", "pages": "1-2"},
        {"artifact_id": "<filled form>"}]}'
```

```js
const form = new FormData();
form.append("to", "+15025551212");
form.append("files", new Blob([pdfBytes], { type: "application/pdf" }), "notice.pdf");

const res = await fetch("https://api.getemboss.ai/fax", {
  method: "POST",
  headers: { Authorization: "Bearer sk_..." },
  body: form,
});
const { job_id } = await res.json();
```

```python
import requests

res = requests.post(
    "https://api.getemboss.ai/fax",
    headers={"Authorization": "Bearer sk_..."},
    data={"to": "+15025551212"},
    files=[("files", ("notice.pdf", open("notice.pdf", "rb"), "application/pdf"))],
)
job_id = res.json()["job_id"]
```

### Response

```json
{
  "job_id": "9edecde3-74d8-4402-bfeb-49e61ca804b9",
  "status": "working",
  "pages": 1,
  "price_cents": 3,
  "destination_masked": "+1502******12",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "source_artifact_ids": ["6c47f7f5-f921-4698-910f-95dd7d81310b"]
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 202 | Accepted; the fax is transmitting. |
| 400 | A JSON body that is not valid JSON or names no to; a source that is not a readable PDF; a page selection that is invalid or out of range; or a fax over 100 pages. |
| 401 | Missing or invalid API key. |
| 402 | The account has no payment method on file. Faxes have no free allowance; the body's code is card_required and billing_url points to the page where one can be added. |
| 404 | Job, form, or artifact not found for this account, or its documents are gone. |
| 409 | The job or form is still processing; poll and send again. |
| 410 | The artifact was already deleted; its bytes cannot be faxed. |
| 413 | The uploaded files together are over 10 MB. |
| 422 | A multipart request with no to or no files, or a destination that was refused: out of the served countries, or blocked. |
| 429 | Too many fax requests; rate limited. |
| 503 | The fax provider did not accept the job; retry. |

## Get a fax receipt

```
GET /fax/{job_id}
```

Authentication: Bearer API key required.

The receipt: working, delivered, failed or expired, with pages and the masked destination; on delivery the price and the hash of the transmitted file; on failure or expiry failure_category, failure_reason, retryable, refund and failed_at.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| job_id | path | uuid | yes | From the send response. |

```curl
curl https://api.getemboss.ai/fax/9edecde3-74d8-4402-bfeb-49e61ca804b9 \
  -H "Authorization: Bearer sk_..."
```

```js
const res = await fetch(`https://api.getemboss.ai/fax/${job_id}`, {
  headers: { Authorization: "Bearer sk_..." },
});
const receipt = await res.json();
```

```python
import requests

res = requests.get(
    f"https://api.getemboss.ai/fax/{job_id}",
    headers={"Authorization": "Bearer sk_..."},
)
receipt = res.json()
```

### Response

```json
{
  "type": "emboss.fax.receipt",
  "job_id": "9edecde3-74d8-4402-bfeb-49e61ca804b9",
  "status": "delivered",
  "to_masked": "+1502******12",
  "pages": 1,
  "provider": "telnyx",
  "submitted_at": "2026-09-12T10:33:29Z",
  "price": { "amount": "0.03", "currency": "USD" },
  "artifact_sha256": "f2ad6f...",
  "delivered_at": "2026-09-12T10:34:00Z",
  "artifact_id": "0f6b2b3e-2c7c-4c47-8c3b-9c7c7a6e5b3a",
  "source_artifact_ids": ["6c47f7f5-f921-4698-910f-95dd7d81310b"]
}
```

### Status codes

| Code | Meaning |
| --- | --- |
| 200 | The receipt. |
| 401 | Missing or invalid API key. |
| 404 | No such job, or owned by another key. |

## See also

- [Send a fax](https://getemboss.ai/docs/send-fax)
- [Send a fax from an agent](https://getemboss.ai/use-cases/send-a-fax-from-an-agent)