Start a fax
create_faxUse this once the person has confirmed the fax number, and given you their email if they aren't signed in. It creates the fax and returns status_url, the page where the person checks the fax number, documents and price, and pays to send it. Nothing is sent or charged until they pay there. Pass the document_ids from create_document. Without them, the fax waits on the status page for the person to add their files. Choose a private random idempotency_key for each intentional new fax. Reuse the exact same key and request after a timeout or request_in_progress; never change the key just to retry. The key is retained for 24 hours. To check a fax, use get_fax_status or get_fax.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"idempotency_key": "<idempotency_key>",
"fax_number": "<fax_number>"
},
"name": "create_fax"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| No | The person's email address, where Faxette sends the receipt and updates. Ask the person for it. Leave it out when they're signed in: their account's email is used. | ||
| region | No | For a fax to the US or Canada from a person who isn't signed in and who the conversation shows is in Europe: pass "eu" to send it through Faxette's European service. It's ignored for other numbers and when the person is signed in. Pass the same value to create_document and create_fax. | |
| content | No | Text approved by the person, rendered as a PDF before the uploaded documents. Markdown supports headings, lists, tables and links as printed text. Images, raw HTML and remote assets are refused. Always show the generated proof before sending. | |
| language | No | The language the person chooses for the fax page, checkout and emails. Check get_capabilities for this region. Omit to use the account preference or regional default. | |
| cover_page | No | An optional cover page. Confirm its wording with the person first. It counts toward the total pages; omit if not requested. | |
| fax_number | Yes | The fax number the fax goes to, in international format, like +14155552671. Numbers in the US, Canada, Mexico, Puerto Rico, Costa Rica, the EU, the UK, Switzerland, Norway, Iceland, Liechtenstein, Monaco, Montenegro, Ukraine and the Isle of Man only. | |
| document_ids | No | The document_id of each file from create_document, in the order they're faxed. Up to 10. Leave it out to let the person add files on the status page. | |
| organization | No | To send as an organization: its id from get_organizations. The fax belongs to the organization and is paid by its plan or card. Leave it out for the person's own fax. | |
| idempotency_key | Yes | A private random UUID for this intentional new fax. Keep it unchanged for retries of the same request within 24 hours. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The fax's id. Pass it to get_fax when the person is signed in. | |
| price | Yes | Before tax. Null until the pages are counted. | |
| status | Yes | draft: waiting for files, or for a file to be fixed. processing_documents: counting pages. documents_ready: ready to pay. awaiting_payment: the person is paying. scheduled: paid, about to dial. sending, delivered, failed. canceled: not paid in time. | |
| attempt | Yes | The current attempt to dial the fax number. | |
| payment | Yes | The person's payment once they start paying, by card or from their credit. amount_cents includes tax. | |
| language | No | ||
| resend_by | Yes | For a failed fax: until when the person can correct the fax number on the status page and send it again. | |
| fax_number | Yes | ||
| page_count | Yes | Null until the pages are counted. | |
| review_url | No | A private review link, valid for 30 minutes. Give it to the person so they can inspect the prepared PDF before paying. | |
| status_url | Yes | The page where the person checks the fax and pays. Give it to them. | |
| max_attempts | Yes | ||
| checkout_quote | No | ||
| failure_reason | Yes | For a failed fax: temporary (busy or no answer on every attempt), wrong_number (no fax machine answered), or our_side. | |
| document_errors | Yes | Files Faxette couldn't use. position is the file's number in the fax. The person fixes them on the status page. | |
| next_attempt_at | Yes | When the next attempt dials, if the line was busy or didn't answer. | |
| checkout_available | Yes | True when the person can pay on the status page. |