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.

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"], "type": "hlr"}'

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.