Email enrichment

POST /v1/lookup/email takes an email address and returns its social footprint: the sites it is registered on, the public profiles behind those accounts, likely usernames, account activity dates and a mailbox check. Use it to enrich a contact record or to see who is behind a sign-up.

Get a key

The Enrich API has its own key, separate from your Web Access key. Contact us to get one. The samples below read the key from STRING_ENRICH_KEY and the address to look up from EMAIL:

export STRING_ENRICH_KEY="your key"
export EMAIL="the address to look up"

Send it as Authorization: Bearer <key> or x-api-key: <key>. Keep it server-side. A missing or wrong key returns 401.

Look up an email

curl https://enrich.usestring.ai/v1/lookup/email \
  -H "Authorization: Bearer $STRING_ENRICH_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"email\": \"$EMAIL\"}" \
  --max-time 180

import os
import requests

res = requests.post(
    "https://enrich.usestring.ai/v1/lookup/email",
    headers={"Authorization": f"Bearer {os.environ['STRING_ENRICH_KEY']}"},
    json={"email": os.environ["EMAIL"]},
    timeout=180,
)
print(res.json())

const res = await fetch("https://enrich.usestring.ai/v1/lookup/email", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STRING_ENRICH_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: process.env.EMAIL }),
  signal: AbortSignal.timeout(180_000),
});
console.log(await res.json());

A new lookup can take up to three minutes, so set your HTTP client timeout to at least 180 seconds. Results are cached for 24 hours, and a cached result returns immediately.

Response

Trimmed to one entry per list:

{
  "ok": true,
  "data": {
    "email": "…",
    "complete": true,
    "sites_checked": 169,
    "profiles": [
      {
        "site": "GitHub",
        "domain": "github.com",
        "profile": { "username": "…", "name": "…", "url": "…", "created_at": "…", "followers": 12 },
        "details": { "company": "…" }
      }
    ],
    "registered_on": [{ "site": "GitHub", "domain": "github.com" }],
    "identity": {
      "verdict": "…",
      "summary": "…",
      "groups": [],
      "accounts": [{ "site": "github", "status": "…", "group": 0 }]
    },
    "usernames": [{ "value": "…", "kind": "username", "likelihood": "likely", "confidence": 0.9, "sites": ["GitHub"] }],
    "mailbox": { "service": "gmail", "accepts_mail": true },
    "activity": {
      "first_seen": "2014-03-02",
      "last_seen": "2026-10-30",
      "events": [{ "date": "2014-03-02", "site": "GitHub", "event": "account_created" }]
    }
  },
  "meta": { "cached": false, "took_ms": 41250 }
}

An address with no footprint returns ok: true with empty profiles and registered_on. That is a real "nothing found", not an error. A field with nothing to report is left out.

Profiles

Each profiles[] entry has site, domain, profile and details. profile holds the common attributes under one name each, when the site reports them: username, name, url, avatar_url, bio, location, created_at, last_active_at, followers and following. details holds any other attributes the site reports, and its keys vary by site.

Check your usage

curl https://enrich.usestring.ai/v1/me \
  -H "Authorization: Bearer $STRING_ENRICH_KEY"

{ "ok": true, "client": "your-org", "usage": { "today": 12, "daily_cap": 500 } }

today counts lookups since 00:00 UTC, cached ones included. Failed lookups are not counted.

Limits

To raise your daily cap, contact us.

Errors

Errors return ok: false with a code:

{ "ok": false, "error": { "code": "busy", "message": "too many lookups in progress, retry shortly" } }

Permitted use

Results describe publicly observable account registrations and profiles for an email address. Do not use them as a factor in decisions about employment, credit, insurance or housing eligibility.