Fax API for Developers

Quick start

Sign in to the JamFax app and open Fax, then API keys (under Settings). Name the key, tick what it may do (fax.send, fax.read, fax.contacts) and create it. Copy the key (it looks like tkgp_xxxxxxxx): it is shown once. You can limit a key to one department; on Corporate Fax every key must be given a department.

Send a fax. The address is https://api.jamfax.com/v1:

curl https://api.jamfax.com/v1/fax/faxes \
  -H "Authorization: Bearer $JAMFAX_KEY" \
  -H "Idempotency-Key: invoice-1042" \
  -F from=+13055550100 -F to=+13055550142 \
  -F "documents[]=@invoice.pdf"

Check it: GET /v1/fax/faxes/{id} returns its status, pages, cost and any error. Download any fax with GET /v1/fax/faxes/{id}/document: you get the searchable PDF by default, or the fax as received with ?original=1.

What the API does

GET /v1/fax/lines: your fax numbers, and whether each can send.
POST /v1/fax/faxes: send PDF or TIFF documents (up to 10, 20 MB together) to one number or up to 50, with an optional cover page (cover[subject], cover[message]) or a time to send (send_at).
GET /v1/fax/faxes: sent and received faxes, newest first, filtered by direction, status, line or since, paged with cursor.
GET, POST, PUT, DELETE /v1/fax/contacts: your fax contacts.

A fax sent through the API is billed like one sent from the browser: it uses your plan's pages, or your Pay-as-you-go credit. Send an Idempotency-Key with every fax: if your request times out, repeating it with the same key and files returns the first answer instead of faxing twice.

Webhooks

Webhooks are for business accounts. Add an endpoint under Webhooks in JamFax and choose the events: fax.received (a fax arrived and is ready), fax.delivered and fax.failed. Each delivery is a JSON POST with a link to the document that works for 60 minutes, so your system needs no API key to fetch it. Failed deliveries are retried for about 15 hours.

The endpoint must be a public https address. Check every delivery's X-TKGVoice-Signature header (t=<time>,v1=<signature>) before trusting it:

import hashlib, hmac, time

def is_genuine(header: str, body: bytes, secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Use the event id to ignore a delivery you have already processed.

Reference and limits

Full reference: API reference (OpenAPI file). The fax operations are under "fax".
Keys expire after one year by default (two years at most) and can be revoked at any time under Settings, API keys.
Each key has a per-minute request limit (120 a minute by default); over it you get a 429 with Retry-After. Hourly sending limits are the same as in the browser.
Sending needs an e-Fax, Corporate Fax or Pay-as-you-go plan. Fax-to-Email lines can read and download faxes.

Questions: support@jamfax.com or (833) 952-6329.

Get a fax number

Questions

Who can use the fax API?

Any JamFax account that can send faxes (e-Fax, Corporate Fax or Pay-as-you-go) can create a key and send. Fax-to-Email lines can read and download faxes. Webhooks are for business accounts.

Can I limit a key to one department?

Yes. A key can be limited to one department and then sees only that department's lines, faxes and contacts. On Corporate Fax every key must be given a department.

What can a key do?

Each key has scopes. fax.read lists lines and faxes and downloads documents, fax.send sends faxes, and fax.contacts manages your fax contacts. Tick only what your software needs.

Which document do I get when I download a fax?

By default you get the searchable PDF of a received fax. Add ?original=1 to the document request to get the fax exactly as it was received.

How do I stop a fax being sent twice?

Send an Idempotency-Key header with every fax. If your request times out, repeat it with the same key and the same files and you get the first answer back instead of a second fax.

How do I know a webhook really came from JamFax?

Each delivery has an X-TKGVoice-Signature header. Compute an HMAC-SHA256 of the timestamp, a dot and the raw request body with your endpoint secret, compare it with the v1 value, and reject a timestamp more than 300 seconds old. The endpoint must be a public https address.

Fax from your own software