Skip to content
Tomba home
Start free

// get /v1/people/find

Person API

Fetch social details tied to an email address name, location, gender, employment, Twitter, LinkedIn, GitHub, Gravatar, and verification status. A drop-in Clearbit Person API replacement.

Get free API keyAPI reference
1 search credit

// api console

GETapi.tomba.io/v1/people/find
Example response from the API reference
name.fullName
Richard Hendricks
email
richard@piedpiper.com
employment.name
Pied Piper
employment.title
CEO
employment.seniority
executive
location
Palo Alto, California, United States
verification.status
valid
phone
true

// 01 · request

Person Enrichment is one HTTPS request

Send the parameters with your key and secret. Every SDK, the CLI and the MCP server make this same call.

GET/people/findParameter
emailrequired
Work email
curl "https://api.tomba.io/v1/people/find?email=richard%40piedpiper.com" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"

// 02 · response

What comes back

JSON, the same in every language. Fields Tomba doesn't know are null, never guessed.

GET/people/findField
data.nameobject
fullName, givenName, familyName
data.employmentobject
Company, domain, title, role, sub-role, seniority
data.location, data.geostring | null, object
Where the person is, as text and as city, state, country, coordinates
data.linkedin, data.twitter, data.github, data.facebookobject
Social handles (twitter and github with their public counts)
data.verificationobject
valid, accept_all, invalid or unknown, and the date of the check
data.phoneboolean
Tomba holds a phone number for the person
meta.emailstring
The address you sent
errorsobject
When nothing is found the response is still 200, with errors {type, message, code} instead of data
GET /people/find
200 OK· 1 search credit
{
  "data": {
    "name": {
      "fullName": "Richard Hendricks",
      "givenName": "Richard",
      "familyName": "Hendricks"
    },
    "email": "richard@piedpiper.com",
    "location": "Palo Alto, California, United States",
    "gender": "male",
    "timeZone": "America/Los_Angeles",
    "utcOffset": -8,
    "geo": {
      "city": "Palo Alto",
      "state": "California",
      "stateCode": "CA",
      "country": "United States",
      "countryCode": "US",
      "lat": 37.4419,
      "lng": -122.143
    },
    "bio": "Founder of Pied Piper.",
    "site": "https://piedpiper.com",
    "avatar": null,
    "employment": {
      "domain": "piedpiper.com",
      "name": "Pied Piper",
      "title": "CEO",
      "role": "executive",
      "subRole": null,
      "seniority": "executive"
    },
    "facebook": {
      "handle": null
    },
    "github": {
      "handle": null,
      "id": null,
      "avatar": null,
      "company": null,
      "blog": null,
      "followers": null,
      "following": null
    },
    "twitter": {
      "handle": null,
      "id": null,
      "bio": null,
      "followers": null,
      "following": null,
      "statuses": null,
      "favorites": null,
      "location": null,
      "site": null,
      "avatar": null
    },
    "linkedin": {
      "handle": "in/richard-hendricks"
    },
    "gravatar": {
      "handle": null,
      "urls": null,
      "avatar": null,
      "avatars": null
    },
    "verification": {
      "date": "2025-01-15T10:32:00+01:00",
      "status": "valid"
    },
    "phone": true,
    "fuzzy": false,
    "emailProvider": "Google",
    "indexedAt": "2025-01-15T10:32:00+01:00",
    "activeAt": "2025-01-15T10:32:00+01:00",
    "inactiveAt": null
  },
  "meta": {
    "email": "richard@piedpiper.com"
  }
}

// 03 · cost and limits

What a call costs

A call is charged only under the condition below. Rate limits depend on your plan.

// cost

1search credit

Charged when: A person is returned.

Errors, 429 and 451 responses, and the same request again within your usage window cost nothing.

How credits work

// rate limits

Requests per second / minute / day
FreeBasicGrowthPro
Search, finder, similar, technology1 / 2 / 53 / 50 / 5005 / 80 / 1,0008 / 150 / 4,000
Email verifier1 / 2 / 102 / 40 / 5003 / 60 / 1,0005 / 100 / 4,000

Pro Plus, Scale and credit packs of 50,000 or more: no limit on these endpoints. Enterprise: no per-second or per-minute limit, 100,000 requests a day. Daily limits reset at 00:00 UTC. Rate limits

// faq

Person API Questions

Still have questions? Visit the help center

// quick start

Make your first call in a minute

Free account, real API key, the same endpoints Enterprise customers use.

  1. 1Create a free account25 searches a month. No card.
  2. 2Copy your key and secretFrom API keys in the dashboard.
  3. 3Call the APIPaste the request; the answer is JSON.
Get free API keyRead the docs
curl "https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks" \
  -H "X-Tomba-Key: $TOMBA_API_KEY" \
  -H "X-Tomba-Secret: $TOMBA_SECRET_KEY"
Response
200 OK· 1 search credit
{
  "data": {
    "email": "richard@piedpiper.com",
    "first_name": "Richard",
    "last_name": "Hendricks",
    "full_name": "Richard Hendricks",
    "website_url": "piedpiper.com",
    "company": "Pied Piper",
    "pattern": "{first}",
    "department": "executive",
    "type": "personal",
    "position": "CEO",
    "country": "US",
    "gender": "male",
    "twitter": null,
    "linkedin": "https://www.linkedin.com/in/richard-hendricks",
    "score": 100,
    "accept_all": false,
    "phone_number": true,
    "verification": {
      "date": "2025-01-15T10:32:00+01:00",
      "status": "valid"
    },
    "sources": [
      {
        "uri": "https://piedpiper.com/blog/engineering",
        "website_url": "piedpiper.com",
        "extracted_on": "2024-06-01T09:14:07+01:00",
        "last_seen_on": "2025-01-10T17:02:44+01:00",
        "still_on_page": true
      }
    ],
    "phone_data": []
  }
}