API reference

Authentication

Send your key in the X-API-Key header. A key is shown once when you create it; we store only a hash.

X-API-Key: pt_live_xxxxxxxxxxxx_<secret>

Endpoints

Filters

Errors

Errors use application/problem+json with a stable code field.

Rate limits

Every authenticated response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.

Events

Events are changes to a carrier's operating authority, recorded by the registry and detected by our checks. You see an event type only when your plan includes a feed that carries it, limited to your plan's states. Businesses on the removal list are never returned. Store next_cursor and pass it back to continue; new events never shift earlier pages.

curl -H "X-API-Key: pt_live_…" "https://…/v1/events?type=insurance_cancellation_suspension&state=TX&since=2026-09-01T00:00:00Z"

Webhooks

Register endpoints in the dashboard or with the API. Each delivery is a POST with a JSON body, retried after 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours, then marked failed. An endpoint is paused after 20 failed deliveries in a row and the account owner is emailed.

Verify every delivery: split the Pingtail-Signature header into t and v1, compute HMAC-SHA256 with your secret over the text t, a dot and the raw request body, compare it with v1 in constant time, and reject a t older than 5 minutes.

Pingtail-Signature: t=1757851200,v1=5f0c…(64 hex)

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

{"id": "evt_1042", "type": "insurance_cancellation_suspension", "created": "2026-09-14T11:16:02+00:00",
 "data": {"usdot": "4600002", "docket": "MC1830002", "state": "TX", "occurred_at": "2026-09-11",
          "source_dataset": "official registry",
          "verify_method": "Recorded in the official registry; detected by our registry checks",
          "data": {"legal_name": "SAMPLE FREIGHT INC", "reason": "Involuntary Suspension - insurance cancellation"}}}