Send a fax

View as Markdown

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/faxBearer auth

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.

Status codes

202Accepted; the fax is transmitting.
400A 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.
401Missing or invalid API key.
402The 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.
404Job, form, or artifact not found for this account, or its documents are gone.
409The job or form is still processing; poll and send again.
410The artifact was already deleted; its bytes cannot be faxed.
413The uploaded files together are over 10 MB.
422A multipart request with no to or no files, or a destination that was refused: out of the served countries, or blocked.
429Too many fax requests; rate limited.
503The fax provider did not accept the job; retry.

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>"}]}'

Response

{
  "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"]
}

Get a fax receipt

GET/fax/{job_id}Bearer auth

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.

Status codes

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

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

Response

{
  "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"]
}