FaxSeal Partner API

Overview

The FaxSeal Partner API lets you provision fax numbers for your users, receive inbound faxes as webhook events, and configure AI extraction schemas so FaxSeal returns structured JSON instead of raw OCR text.

• Every partner gets a Partner Key — used as X-Partner-Key on all requests
• Users are identified by externalUserId — a stable ID from your system (e.g. mp_42)
• A single shared inbox can be provisioned via externalUserId: "mp_public_inbox"
• Webhook events fire on fax.received (OCR complete) and fax.extracted (schema parsed)

Base URL: https://faxseal.com/api/partner

Authentication

All requests require your partner key in the X-Partner-Key header. Keys are generated by FaxSeal — contact us to get one.

curl https://faxseal.com/api/partner/inbox \
  -H "X-Partner-Key: sk_partner_YOUR_KEY_HERE"

Keep your key secret — it has full access to all users in your partner account.

Inbox API

List received faxes

Returns the 50 most recent faxes for the authenticated partner, across all external user IDs.

GET /api/partner/inbox

Response 200:
{
  "faxes": [
    {
      "id": "clxyzabc",
      "faxId": "fax_123",
      "externalUserId": "mp_42",
      "fromNumber": "+15125551234",
      "toNumber": "+12083617587",
      "pages": 2,
      "ocrText": "THE GOLDEN FORK\n1234 Main St\nAustin TX...",
      "ocrStatus": "success",
      "extractedData": { "restaurant_name": "The Golden Fork", ... },
      "extractStatus": "success",
      "receivedAt": "2026-04-18T14:22:00Z"
    }
  ]
}

fax.received event payload

Fired when OCR finishes (usually within 30 seconds of receiving the fax).

{
  "event": "fax.received",
  "faxId": "fax_123",
  "externalUserId": "mp_42",
  "fromNumber": "+15125551234",
  "toNumber": "+12083617587",
  "pages": 2,
  "ocrText": "THE GOLDEN FORK\n...",
  "receivedAt": "2026-04-18T14:22:00Z"
}

Webhook events

Set your webhook URL via the Settings API. FaxSeal delivers events with up to 3 retry attempts (1 min → 5 min → 25 min backoff) and a 10-second timeout per attempt.

Securing your endpoint

Set FAXSEAL_WEBHOOK_SECRET in your environment. FaxSeal sends it asX-Webhook-Secret on every delivery.

// Next.js webhook route example
const secret = req.headers.get('x-webhook-secret');
if (process.env.FAXSEAL_WEBHOOK_SECRET &&
    secret !== process.env.FAXSEAL_WEBHOOK_SECRET) {
  return Response.json({ error: 'Unauthorized' }, { status: 401 });
}

AI Extraction

When an extractionSchema is set on your partner account, FaxSeal runs GPT-4o-mini over the OCR text and fires a fax.extracted webhook with structured JSON.

Schema format

The schema defines which fields to extract. Each field has a name and a type: string, number, boolean, array, or object.

{
  "type": "restaurant_menu",
  "fields": [
    { "name": "restaurant_name", "type": "string"  },
    { "name": "address",         "type": "string"  },
    { "name": "city",            "type": "string"  },
    { "name": "state",           "type": "string"  },
    { "name": "phone",           "type": "string"  },
    { "name": "website",         "type": "string"  },
    { "name": "category",        "type": "string"  },
    { "name": "items",           "type": "array"   },
    { "name": "effective_date",  "type": "string"  }
  ]
}

items is an array of { name: string, price: number } objects. Fields not found in the fax are returned as null.

fax.extracted event payload

{
  "event": "fax.extracted",
  "faxId": "fax_123",
  "externalUserId": "mp_42",
  "fromNumber": "+15125551234",
  "extracted": {
    "restaurant_name": "The Golden Fork",
    "address": "1234 Main Street",
    "city": "Austin",
    "state": "TX",
    "phone": "5125550100",
    "website": "www.goldenfork.com",
    "category": "American",
    "items": [
      { "name": "Classic Burger",       "price": 12.99 },
      { "name": "BBQ Bacon Burger",     "price": 14.99 },
      { "name": "Caesar Salad",         "price":  9.99 }
    ],
    "effective_date": null
  }
}

Settings API

GET /api/partner/settings

Returns current partner configuration.

curl https://faxseal.com/api/partner/settings \
  -H "X-Partner-Key: sk_partner_YOUR_KEY_HERE"

Response 200:
{
  "name": "MarketPulse",
  "webhookUrl": "https://getmarketpulse.com/api/faxseal/webhook",
  "billingEmail": "[email protected]",
  "extractionSchema": { ... },
  "createdAt": "2026-01-01T00:00:00Z"
}

PATCH /api/partner/settings

Update webhookUrl and/or extractionSchema. Both fields are optional.

curl -X PATCH https://faxseal.com/api/partner/settings \
  -H "X-Partner-Key: sk_partner_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{"webhookUrl":"https://yourapp.com/api/faxseal/webhook"}'

Response 200:
{ "ok": true }

Numbers API

GET /api/partner/numbers

Returns all fax numbers provisioned under your partner account and their assigned users.

curl https://faxseal.com/api/partner/numbers \
  -H "X-Partner-Key: sk_partner_YOUR_KEY_HERE"

Response 200:
{
  "numbers": [
    {
      "faxNumber": "+12083617587",
      "externalUserId": "mp_public_inbox",
      "createdAt": "2026-01-01T00:00:00Z"
    }
  ]
}

Limits & best practices

• Webhook delivery timeout: 10 seconds. Respond with 2xx quickly; process asynchronously.
• Retry schedule: 1 min → 5 min → 25 min. After 3 failures the delivery is marked failed.
• Extraction adds ~30s latency. fax.received fires first; fax.extracted fires after.
• Rate limit: 60 API requests per minute per partner key.
• Fax files are stored for 30 days, then purged. Download OCR text from the inbox if you need long-term retention.