String docs

Enrich API

Look up an email's social footprint, find public profiles under a username, or find a person's email addresses from LinkedIn or a name.

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.

Two more lookups share the same key and daily cap. POST /v1/lookup/username checks about 170 consumer sites for a public profile under a handle. POST /v1/lookup/linkedin finds a person's probable email addresses from a LinkedIn profile URL, or from a name and company.

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());
FieldTypeDefaultDescription
emailstring—Required. The address to look up. Up to 254 characters, 64 before the @.
freshbooleanfalsetrue ignores a result cached in the last 24 hours and runs a new lookup.

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.

Email 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 }
}
FieldTypeDescription
emailstringThe address looked up.
completebooleantrue when every site finished checking.
sites_checkednumberHow many sites were checked.
profilesarraySites with an account on this address and profile details. See Profiles.
registered_onarrayEvery site where the address is registered, as site and domain.
identityobjectWhether the accounts appear to belong to one person: verdict, summary, groups, and accounts[] with site, status and group.
usernamesarrayLikely usernames for the person: value, kind, likelihood, confidence from 0 to 1, and the sites it came from.
mailboxobjectservice, the mailbox service (for example gmail), and accepts_mail.
activityobjectfirst_seen and last_seen in ISO 8601, and events[] with date, site and event: account_created, last_login or last_seen.
meta.cachedbooleantrue when the result came from the 24-hour cache.

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.

Look up a username

POST /v1/lookup/username checks about 170 consumer sites (social, creator, fitness, reading, music, gaming, art, travel, shopping and developer sites) for a public profile under a handle. Use it when you have a handle or a name rather than an email address. The sample reads the handle from HANDLE:

curl https://enrich.usestring.ai/v1/lookup/username \
  -H "Authorization: Bearer $STRING_ENRICH_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$HANDLE\", \"categories\": [\"social\", \"fitness\"]}" \
  --max-time 300

Send at least one of username, usernames or name. Together they can ask for at most 6 handles.

FieldTypeDefaultDescription
usernamestringnoneA handle, with or without a leading @. 1 to 64 letters, digits, ., _ or -.
usernamesstring[]noneSeveral handles, same rules as username.
namestringnoneA person's full name. Adds 5 common handle forms, for Jane Doe: jane.doe, janedoe, jdoe, janed, doejane.
categoriesstring[]allCheck only these site categories: art, creator, dev, fitness, food, gaming, music, reading, shopping, social, travel, video.
freshbooleanfalsetrue ignores a result cached in the last 24 hours and runs a new lookup.

A full check of one handle can take a few minutes, so set your HTTP client timeout to at least 300 seconds, or pass categories for a faster check. Results are cached for 24 hours.

Username response

{
  "ok": true,
  "data": {
    "handles": [
      {
        "handle": "janedoe",
        "found": [{ "site": "Strava", "category": "fitness", "url": "https://www.strava.com/athletes/janedoe" }],
        "counts": { "found": 1, "missing": 40, "unknown": 2 }
      }
    ],
    "sites_checked": 43
  },
  "meta": { "cached": false, "took_ms": 6000 }
}
FieldTypeDescription
handles[].handlestringThe handle checked, lowercased and without @.
handles[].foundarraySites with a public profile under this handle: site, category and the profile url.
handles[].countsobjectHow many sites returned found, missing (no profile) or unknown (no clear answer).
sites_checkednumberHow many sites were checked for each handle.

found means a public profile exists under that handle. It does not prove the profile belongs to the person you have in mind: a common handle is often someone else's, so confirm on the profile itself.

Find a person's email from LinkedIn

POST /v1/lookup/linkedin returns a person's probable email addresses, work and personal, from a LinkedIn profile URL. When you have no URL, send name and company instead. The sample reads the profile URL from LINKEDIN_URL:

curl https://enrich.usestring.ai/v1/lookup/linkedin \
  -H "Authorization: Bearer $STRING_ENRICH_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"linkedin_url\": \"$LINKEDIN_URL\"}" \
  --max-time 180
FieldTypeDefaultDescription
linkedin_urlstringnoneRequired unless name is sent. A linkedin.com profile URL.
namestringnoneRequired unless linkedin_url is sent. The person's full name.
companystringnoneThe person's employer. Needed for work addresses when you send name without a URL.
handlestringnoneA social handle you already know for the person. Improves personal-address results.
personalbooleantruefalse returns work addresses only.
freshbooleanfalsetrue ignores a result cached in the last 24 hours and runs a new lookup.

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

LinkedIn response

{
  "ok": true,
  "data": {
    "person": { "name": "…", "company": "…", "domain": "example.com" },
    "emails": [
      { "address": "…", "kind": "work", "source": "pattern", "confidence": 0.8, "verified": true }
    ],
    "notes": ["…"]
  },
  "meta": { "cached": false, "took_ms": 61230 }
}
FieldTypeDescription
personobjectWho the lookup resolved: name, company, linkedin_url and the company email domain, when known.
emailsarrayProbable addresses, highest confidence first.
emails[].kindstringwork (the company's domain) or personal (a personal mailbox).
emails[].sourcestringpublished (found as written on a public page), pattern (built from the company's address format), public_listing (a public listing page) or derived (a likely address that matched the person).
emails[].confidencenumberFrom 0 to 1.
emails[].verifiedbooleantrue when the address resolved in an email lookup and nothing found for it contradicts the person's name. Treat an unverified address as a lead.
notesarrayShort notes on what the lookup did and did not find, so a thin result explains itself.

An empty emails list with ok: true means no address was found. It is not an error.

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 email, username and LinkedIn lookups since 00:00 UTC, cached ones included. Each call counts as one lookup, however many handles it checks. Failed lookups are not counted.

Limits

LimitValueWhen you hit it
Lookups per dayYour key's daily_cap from /v1/me, resetting at 00:00 UTC429 with daily_cap
New lookups at once2 email or LinkedIn lookups per key, shared, plus 1 username lookup. Cached results are always served.429 with busy
Handles per username lookup6400 with bad_request
Request body16 KB413

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" } }
StatuscodeMeaningRetryCounted
400bad_requestA required field is missing or invalid: email not an address, a handle with other characters, more than 6 handles, an unknown category, or a linkedin_url that isn't a linkedin.com URL.No. Fix the body.No
401unauthorizedMissing or wrong key.No. Check the key.No
404not_foundUnknown path or method.No.No
413—Body over 16 KB.No.No
429busyTwo email or LinkedIn lookups, or one username lookup, are already running on your key.After the retry-after header (15 s; 60 s for username).No
429daily_capDaily cap reached.After 00:00 UTC.No
502lookup_failedThe lookup failed.Once.No
503over_capacityTemporarily out of capacity.After the retry-after header.No

Permitted use

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