Skip to content
DocsSign in
Browse the docs

Quickstart

Send your first fax from your terminal. You need a XipFax account and a PDF at a public link.

1. Make an API key

Sign in to the developer console, open API keys and make a key. You see it whole just once, so copy it then. Every key is live: what it sends is real.

Keep it in your shell for the steps below:

Your shell
export XIPFAX_API_KEY=xipfax_key_live_…

2. Ask what a fax costs

This costs nothing, and it shows your key works.

Request
curl "https://api.xipfax.com/quote?pages=3" \
  -H "Authorization: Bearer $XIPFAX_API_KEY"
200 OK
{
  "pages": 3,
  "price": {
    "amount_minor": 499,
    "currency": "USD"
  },
  "price_shown": "$4.99",
  "terms": "$4.99 for up to 10 pages, then 20¢ a page. Nothing if it fails.",
  "price_list": "2026-10-22"
}

3. Add a document

Your account has one draft, the fax you’re preparing. Add a PDF to it by a link XipFax can fetch: https, public, and answering with the PDF itself. Each POST names a key of your own in Idempotency-Key, so that a retry can’t add it twice. No uuidgen? Any unique string of up to 255 printable ASCII characters works.

Request
curl -X POST "https://api.xipfax.com/draft/documents" \
  -H "Authorization: Bearer $XIPFAX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "lease.pdf",
    "url": "https://example.com/lease.pdf"
  }'
201 Created
{
  "document": {
    "id": "01JC0000000000000000000002",
    "name": "lease.pdf",
    "size_bytes": 48210,
    "page_count": 3,
    "status": "ready",
    "url": "https://…"
  },
  "upload": null
}

4. Check the draft

The draft lists its documents in the order the fax sends them. Keep their ids for the next step.

Request
curl "https://api.xipfax.com/draft" \
  -H "Authorization: Bearer $XIPFAX_API_KEY"
200 OK
{
  "id": "01JC0000000000000000000001",
  "documents": [
    {
      "id": "01JC0000000000000000000002",
      "name": "lease.pdf",
      "size_bytes": 48210,
      "page_count": 3,
      "status": "ready",
      "url": "https://…"
    }
  ]
}

5. Send the fax

This step sends a real fax, and it’s charged. It goes to the number you name, so name one of your own. Its pages count on your plan, or where you have no plan its price is held on the card you saved, and taken once it’s delivered. A fax that fails costs nothing.

Name your fax number and the draft’s documents, in their order. A draft whose documents aren’t these is refused, so that nothing you didn’t name is sent.

Request
curl -X POST "https://api.xipfax.com/draft/send" \
  -H "Authorization: Bearer $XIPFAX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "fax_number": "+1 202 555 0143",
    "document_ids": [
      "01JC0000000000000000000002"
    ]
  }'
200 OK
{
  "fax": {
    "id": "01JC0000000000000000000001",
    "direction": "sent",
    "status": "sending",
    "step": "queued",
    "office_id": null,
    "to_number": "+12025550143",
    "from_number": "+12025550100",
    "pages": 3,
    "price": {
      "amount_minor": 499,
      "currency": "USD"
    },
    "sent_at": "2026-11-05T15:04:05.000Z",
    "finished_at": null,
    "retry_at": null,
    "failure": null,
    "time_zone": "America/New_York",
    "sender_name": "Alex Example",
    "cover_confidential": false
  },
  "paid_by": "card",
  "confirm_url": null
}

paid_by says how it’s paid: plan or card. Where XipFax can’t send it without you, as when you have neither or your bank asks you to confirm, nothing is sent or held: paid_by is null, and confirm_url is the link where the fax waits for you on xipfax.com.

6. Follow the fax

Keep the id the send gave in your shell, and read the fax by it until its status is delivered or failed.

Your shell
export FAX_ID=01JC0000000000000000000001
Request
curl "https://api.xipfax.com/faxes/$FAX_ID" \
  -H "Authorization: Bearer $XIPFAX_API_KEY"

Once it’s delivered, its confirmation says who received how many pages, from whom and when:

Request
curl "https://api.xipfax.com/faxes/$FAX_ID/confirmation" \
  -H "Authorization: Bearer $XIPFAX_API_KEY"

Next

  • Webhooks: how XipFax will tell your server a fax has ended, once you can register an endpoint.
  • The API reference: every operation, event and object.