FaxSeal Send API

Overview

The FaxSeal Send API has three endpoints — one for each input type. All three share the same authentication, credit model, and response format.

Base URL

https://faxseal.com

All endpoints accept JSON (or multipart for file upload) and return JSON.

Authentication

Every request must include your API token in the Authorization header as a Bearer token. Tokens are generated from your API Tokens dashboard. Tokens beginning with fsx_ are personal tokens; tokens created while in a Team workspace are scoped to that team's credit pool.

Authorization: Bearer fsx_your_token_here

Tokens inactive for 90 days are automatically revoked. Tokens used regularly stay active indefinitely. You can have up to 5 active tokens — create one per integration so you can revoke independently.

Endpoints

curl -X POST https://faxseal.com/api/fax-from-url \
  -H "Authorization: Bearer fsx_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/press-release.pdf",
    "toNumber": "+12025551234",
    "note": "Please review the attached document."
  }'

{
  "jobId": "cmo3abc123",
  "status": "queued",
  "pages": 3,
  "trackUrl": "https://faxseal.com/track?jobId=cmo3abc123",
  "creditsRemaining": 47
}

curl -X POST https://faxseal.com/api/fax-from-file \
  -H "Authorization: Bearer fsx_your_token" \
  -F "file=@/path/to/document.pdf" \
  -F "toNumber=+12025551234" \
  -F "note=Urgent: please respond within 48 hours."

{
  "jobId": "cmo3def456",
  "status": "queued",
  "pages": 5,
  "trackUrl": "https://faxseal.com/track?jobId=cmo3def456",
  "creditsRemaining": 42
}

curl -X POST https://faxseal.com/api/fax-from-selection \
  -H "Authorization: Bearer fsx_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Dear Senator Smith,</h1><p>We urge you to support S.1234...</p>",
    "toNumber": "+12025551234"
  }'

{
  "jobId": "cmo3ghi789",
  "status": "queued",
  "pages": 1,
  "trackUrl": "https://faxseal.com/track?jobId=cmo3ghi789",
  "creditsRemaining": 41
}

Check Fax Status

curl "https://faxseal.com/api/status?jobId=cmo3abc123" \
  -H "Authorization: Bearer fsx_your_token"

Error Codes

All errors return JSON with an error string. HTTP status codes follow standard conventions.

Error response shape

{
  "error": "Insufficient credits",
  "creditsRequired": 2,
  "creditsAvailable": 1
}

Credits & Pricing

All send endpoints use pre-purchased credits. Credits never expire. Unused credits are automatically restored on fax failure.

High-volume users can purchase multiple packs at once. Org (team) tokens share a single credit pool — ideal for platforms sending on behalf of many users.Buy credits →

Limits

Code Examples

JavaScript / Node.js — Fax a PDF file

const fs = require('fs');
const FormData = require('form-data');
const fetch = require('node-fetch');

async function sendFax(filePath, toNumber) {
  const form = new FormData();
  form.append('file', fs.createReadStream(filePath), { contentType: 'application/pdf' });
  form.append('toNumber', toNumber);

  const res = await fetch('https://faxseal.com/api/fax-from-file', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer fsx_your_token',
      ...form.getHeaders(),
    },
    body: form,
  });

  const data = await res.json();
  if (!res.ok) throw new Error(data.error);
  return data; // { jobId, status, pages, trackUrl, creditsRemaining }
}

sendFax('./letter.pdf', '+12025551234').then(console.log);

JavaScript — Fax from a URL

const res = await fetch('https://faxseal.com/api/fax-from-url', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer fsx_your_token',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://yoursite.com/documents/advocacy-letter.pdf',
    toNumber: '+12025551234',
  }),
});
const { jobId, creditsRemaining } = await res.json();

Python — Fax HTML (mail-merge template)

import requests

def fax_letter(to_number: str, legislator_name: str, issue: str) -> dict:
    html = f"""
    <h2>Dear {legislator_name},</h2>
    <p>I am writing to urge your support for {issue}.</p>
    <p>As your constituent, I believe this measure is essential...</p>
    <p>Sincerely,<br>A Concerned Constituent</p>
    """
    resp = requests.post(
        'https://faxseal.com/api/fax-from-selection',
        headers={'Authorization': 'Bearer fsx_your_token'},
        json={'html': html, 'toNumber': to_number},
    )
    resp.raise_for_status()
    return resp.json()  # { jobId, status, pages, trackUrl, creditsRemaining }

# Send to multiple offices
offices = [
    ('+12025550001', 'Senator Johnson', 'S.1234 — Clean Water Act Amendment'),
    ('+12025550002', 'Rep. Williams',   'H.R.5678 — Infrastructure Bill'),
]
for number, name, issue in offices:
    result = fax_letter(number, name, issue)
    print(f"Queued: {result['jobId']} — {result['creditsRemaining']} credits remaining")

Python — Poll for delivery

import time, requests

def wait_for_delivery(job_id: str, token: str, timeout=300) -> str:
    start = time.time()
    while time.time() - start < timeout:
        r = requests.get(
            f'https://faxseal.com/api/status?jobId={job_id}',
            headers={'Authorization': f'Bearer {token}'},
        )
        data = r.json()
        if data['status'] in ('delivered', 'failed'):
            return data['status']
        time.sleep(30)
    return 'timeout'

Use Cases