Feed API — pull

If exposing a read-only endpoint is easier for you than pushing webhooks, give us a feed URL and a bearer token — we poll it, typically every 5 minutes.

When to choose this. Push (the Events API) gets leads to an agent within seconds and is the recommended default — speed-to-lead is the biggest conversion driver in phone recovery. Choose the feed model when webhooks are impractical on your side; the polling interval becomes your worst-case delivery latency.

The contract

GET https://your-host/leads-feed?since={iso8601}&cursor={opaque}

Authorization: Bearer <token you issue to us>

// response
{
  "count": 42,
  "next_cursor": "abc123",   // empty/absent when no more pages
  "items": [ { …lead, same fields as the Events API… } ]
}

Auth: a single bearer token you issue to us — rotatable, read-only scope.
Incremental: we pass since (last successful poll) — return everything created or updated after it.
Pagination: return a next_cursor; we loop until it's empty. Any page size is fine.
Items: each item uses the same fields as the Events API field reference — lead_id and phone required, everything else recommended or optional. Your existing field names are fine; we map from one sample.
Idempotency: overlapping windows and repeated items are safe — we de-dupe on lead_id.

Going live — the checklist

You send us the feed URL, a bearer token, and one sample response.
We confirm the mapping and start polling against a test window.
Seed check: we verify a known test lead comes through with a working phone number.