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 180import 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());| Field | Type | Default | Description |
|---|---|---|---|
email | string | — | Required. The address to look up. Up to 254 characters, 64 before the @. |
fresh | boolean | false | true 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 }
}| Field | Type | Description |
|---|---|---|
email | string | The address looked up. |
complete | boolean | true when every site finished checking. |
sites_checked | number | How many sites were checked. |
profiles | array | Sites with an account on this address and profile details. See Profiles. |
registered_on | array | Every site where the address is registered, as site and domain. |
identity | object | Whether the accounts appear to belong to one person: verdict, summary, groups, and accounts[] with site, status and group. |
usernames | array | Likely usernames for the person: value, kind, likelihood, confidence from 0 to 1, and the sites it came from. |
mailbox | object | service, the mailbox service (for example gmail), and accepts_mail. |
activity | object | first_seen and last_seen in ISO 8601, and events[] with date, site and event: account_created, last_login or last_seen. |
meta.cached | boolean | true 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 300Send at least one of username, usernames or name. Together they can ask for at most 6 handles.
| Field | Type | Default | Description |
|---|---|---|---|
username | string | none | A handle, with or without a leading @. 1 to 64 letters, digits, ., _ or -. |
usernames | string[] | none | Several handles, same rules as username. |
name | string | none | A person's full name. Adds 5 common handle forms, for Jane Doe: jane.doe, janedoe, jdoe, janed, doejane. |
categories | string[] | all | Check only these site categories: art, creator, dev, fitness, food, gaming, music, reading, shopping, social, travel, video. |
fresh | boolean | false | true 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 }
}| Field | Type | Description |
|---|---|---|
handles[].handle | string | The handle checked, lowercased and without @. |
handles[].found | array | Sites with a public profile under this handle: site, category and the profile url. |
handles[].counts | object | How many sites returned found, missing (no profile) or unknown (no clear answer). |
sites_checked | number | How 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| Field | Type | Default | Description |
|---|---|---|---|
linkedin_url | string | none | Required unless name is sent. A linkedin.com profile URL. |
name | string | none | Required unless linkedin_url is sent. The person's full name. |
company | string | none | The person's employer. Needed for work addresses when you send name without a URL. |
handle | string | none | A social handle you already know for the person. Improves personal-address results. |
personal | boolean | true | false returns work addresses only. |
fresh | boolean | false | true 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 }
}| Field | Type | Description |
|---|---|---|
person | object | Who the lookup resolved: name, company, linkedin_url and the company email domain, when known. |
emails | array | Probable addresses, highest confidence first. |
emails[].kind | string | work (the company's domain) or personal (a personal mailbox). |
emails[].source | string | published (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[].confidence | number | From 0 to 1. |
emails[].verified | boolean | true 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. |
notes | array | Short 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
| Limit | Value | When you hit it |
|---|---|---|
| Lookups per day | Your key's daily_cap from /v1/me, resetting at 00:00 UTC | 429 with daily_cap |
| New lookups at once | 2 email or LinkedIn lookups per key, shared, plus 1 username lookup. Cached results are always served. | 429 with busy |
| Handles per username lookup | 6 | 400 with bad_request |
| Request body | 16 KB | 413 |
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" } }| Status | code | Meaning | Retry | Counted |
|---|---|---|---|---|
400 | bad_request | A 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 |
401 | unauthorized | Missing or wrong key. | No. Check the key. | No |
404 | not_found | Unknown path or method. | No. | No |
413 | — | Body over 16 KB. | No. | No |
429 | busy | Two 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 |
429 | daily_cap | Daily cap reached. | After 00:00 UTC. | No |
502 | lookup_failed | The lookup failed. | Once. | No |
503 | over_capacity | Temporarily 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.