Batch lookups

Request

Each item takes the same fields a single lookup does — email, phone, ip or a free-form query - and, as on POST /v2/lookup, an item can carry email and phone together and its own checks. Items can be of different kinds in the same batch.

curl -X POST https://api.digifootprint.dev/v2/lookup/batch \
  -H "Authorization: Bearer dfp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "email": "someone@example.com", "phone": "+14155552671", "checks": { "email": true } },
      { "ip": "8.8.8.8", "checks": { "footprint": false, "ip": true } },
      { "query": "someuser" }
    ]
  }'

{
  "results": [
    { "index": 0, "lookupId": "ba29e92b-b25b-4819-92d8-68c18c204eef", "status": "queued" },
    { "index": 1, "lookupId": "37b00a85-181e-4e6b-8a2b-f59e617ad751", "status": "queued" },
    { "index": 2, "lookupId": "1dea04b7-e713-4a76-900e-0f4a2995ee00", "status": "queued" }
  ]
}

It queues, it does not wait

A full sweep takes tens of seconds, so fifty of them could never be one synchronous response. The call returns as soon as the work is queued — typically in well under a second — and each item gets its own lookupId to read back.

curl https://api.digifootprint.dev/v2/lookup/ba29e92b-b25b-4819-92d8-68c18c204eef \
  -H "Authorization: Bearer dfp_live_..."

A lookup still in flight answers with "status": "processing". Poll every few seconds rather than in a tight loop; read requests have their own rate limit. A finished lookup reads back as the full v2 response - footprint, modules and risk.

Items succeed and fail independently

A malformed item is rejected up front. If any item is not a valid email, phone or IP, the whole request returns 400 and nothing is billed. The same applies to an empty batch or one with more than 50 items.

Once accepted, items are billed and queued one at a time. If you run out of credit partway through, the items already queued stay queued and the rest come back with an error entry — because by then they have been charged, and there is no way to un-charge them.

{
  "results": [
    { "index": 0, "lookupId": "ba29e92b-...", "status": "queued" },
    { "index": 1, "status": "error",
      "error": { "code": "insufficient_credits", "message": "Top up to continue." } }
  ]
}

Match entries by index, which is the position in the array you sent.

Limits and billing

Up to 50 items per call. Every item is billed as its own lookup (by the modules it runs, as listed in meta.modules when you read it back), so a batch of 50 costs the same as 50 single calls — the endpoint saves round trips, not credits. Batch requests carry their own, lower per-minute rate limit than ordinary lookups, since one call can be worth fifty.