Connect ESXPress to Your Stack

Register a webhook

# Configure a webhook (100 plan or above, or API add-on)
curl -X POST https://esxpress.org/api/v1/webhooks/configure \
  -H "Authorization: Bearer <your-jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
    "secret": "your-hmac-secret",
    "is_active": true
  }'

# Manage: GET /api/v1/webhooks · PATCH /api/v1/webhooks/{id} · DELETE /api/v1/webhooks/{id}
# HTTPS only, cleartext http:// is rejected (payloads contain PII).
# When a secret is set, every delivery carries:
#   X-Webhook-Signature: sha256=<hmac-hex>
#   X-Webhook-Timestamp: <unix-epoch>
#   X-Webhook-Signature-Version: v1

Payload delivered on every conversion (event: conversion.completed)

{
  "event": "conversion.completed",
  "tenant_id": 1,
  "tenant_name": "Acme Roofing",
  "tenant_slug": "acme",
  "conversion_id": 42,
  "filename": "scope.pdf",
  "esx_filename": "42_SAMPLE.esx",
  "esx_download_url": "https://esxpress.org/api/v1/public/convert/42/download",
  "esx_ready": true,
  "status": "ready",
  "total_line_items": 24,
  "total_rcv": 15234.56,
  "carrier_name": "StateFarm",
  "claim_number": "22-ABC-1234",
  "insured_name": "John Doe",
  "property_address": "123 Main St",
  "timestamp": "2026-08-07T01:32:00Z",
  "source": "esxpress"
}

End-to-end with curl

# Preferred for accuracy: structured XML intake, send scope XML (Xactimate's or any other system's), no OCR in the path
curl -X POST https://esxpress.org/api/v1/public/convert/structured?build=1 \
  -H "X-API-Key: esx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/xml" \
  --data-binary @scope.xml

# PDF intake (multipart; up to 50MB per file, batch supported)
curl -X POST https://esxpress.org/api/v1/public/convert/upload \
  -H "X-API-Key: esx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "files=@scope.pdf" \
  -F "carrier=StateFarm"

# → { "ok": true, "jobs": [ { "filename": "scope.pdf", "task_id": "...", "conversion_id": 42 } ], ... }

# Poll status until "ready"
curl -H "X-API-Key: esx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://esxpress.org/api/v1/public/convert/42/status

# Download the ESX file
curl -OJ -H "X-API-Key: esx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  https://esxpress.org/api/v1/public/convert/42/download

Commands

Commands                     What it does
──────────────────────────────────────────────────────────────
/esxpress upload <pdf-url>    Convert a scope from a PUBLIC PDF URL
                              (optional: carrier:StateFarm)
/esxpress status <job-id>     Check conversion status
/esxpress list [N]            List recent conversions (default 5)
/esxpress help                Show usage guide