Bulk lookups

For volumes beyond a single request, submit a batch and poll for results. This is a separate code path from the sync endpoint, so a large batch never adds latency to your single-lookup calls.

[TO BE CONFIRMED] This endpoint is live and processes real submissions, but the queue it depends on (Upstash QStash) isn't configured in production yet — until it is, batches complete with every row refunded rather than a real verdict. For a real, working bulk check right now, use the dashboard's own Bulk Verify page (/app/bulk-verify) or the free /tools/bulk-checker tool.

1. Submit a batch

curl -X POST https://api.usefilter.io/api/v1/filter/bulk \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["+919876543210", "+919876500000"], "source": "website"}'

Credits for the entire batch are reserved upfront, atomically. If your balance can't cover the full batch, nothing is queued and you get 402 — never a partially-processed batch you didn't expect.

2. Poll for results

curl https://api.usefilter.io/api/v1/filter/bulk/btch_a1b2c3d4 \
  -H "Authorization: Bearer YOUR_API_KEY"

Poll no more than once every 5 seconds. results grows as rows complete — it will be empty immediately after submission.

Limits

• —1,000 phone numbers maximum per batch.
• —Each row follows the same credit and cache rules as a single lookup.
• —Outbound webhooks (a push notification when your batch finishes) are on the roadmap but not available yet — for now, polling is the only option.