Running a lookup

Send one of query, email, or phone. Use query when you don't know which you have, since it is auto-detected.

Synchronous

?wait=true blocks until every platform has answered. Simplest to integrate; expect several seconds.

POST /v1/lookup?wait=true
curl -X POST "https://api.digifootprint.dev/v1/lookup?wait=true" \
  -H "Authorization: Bearer dfp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "someone@example.com"}'

Queued

Without ?wait=true you get a lookupId straight away and poll for the result. For a responsive UI, prefer streaming over polling.

POST /v1/lookup
# Returns immediately with an id to poll
curl -X POST "https://api.digifootprint.dev/v1/lookup" \
  -H "Authorization: Bearer dfp_your_key" \
  -H "Content-Type: application/json" \
  -d '{"query": "someone@example.com"}'

# {"lookupId": "8f2c...", "status": "processing"}

curl "https://api.digifootprint.dev/v1/lookup/8f2c..." \
  -H "Authorization: Bearer dfp_your_key"

The response

200 OK
{
  "lookupId": "8f2c1d3e-...",
  "query": "someone@example.com",
  "platformsChecked": 844,
  "matches": 3,
  "socialMatches": 2,
  "servedFromCache": false,
  "results": [
    {
      "platform": "github",
      "registered": true,
      "method": "public_api",
      "icon": "https://.../github.svg",
      "checkedAt": "2026-08-26T11:40:55.902Z"
    },
    {
      "platform": "google",
      "registered": true,
      "method": "domain_derived",
      "icon": "https://.../google.svg",
      "checkedAt": "2026-08-26T11:40:55.902Z",
      "mailboxProvider": true
    }
  ],
  "breaches": [{ "name": "Adobe", "date": "2013-10-04" }],
  "webMentions": null,
  "phoneDetails": null
}

Absent is not negative. A platform we could not get a confident answer for is omitted from results entirely, rather than returned as registered: false. Not every one of the platforms we check will appear. A site that blocked us or timed out is an unknown, and we will not report an unknown as a fact.

null is not empty. breaches and webMentions are null when that source is not enabled for your account, which is a different fact from [] meaning we checked and found nothing.

matches vs socialMatches. matches counts every registration. socialMatches excludes accounts that came with the email address rather than being signed up for. A Microsoft 365 tenant provisions an account for every employee, so that result is true of the whole company and says nothing about the individual. Those carry mailboxProvider: true. For fraud scoring, socialMatches is usually the number you want.

Listing past lookups

Scoped to your own account, most recent first. Limited to 20 requests a minute, see rate limits.

GET /v1/lookup
curl "https://api.digifootprint.dev/v1/lookup?limit=20&offset=0" \
  -H "Authorization: Bearer dfp_your_key"