// get /v1/email-finder
Email Finder API
Find professional email addresses using a name and company domain via our RESTful API.
1 search credit
// api console
Example response from the API reference
- richard@piedpiper.com
- full_name
- Richard Hendricks
- position
- CEO
- company
- Pied Piper
- score
- 100
- verification.status
- valid
- type
- personal
- accept_all
- false
- sources
- 1 item
// 01 · request
Email Finder 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
/email-finderParameterdomainpiedpiper.com- Company domain (or send company)
first_nameRichard- First name (or send full_name)
last_nameHendricks- Last name
enrich_mobilefalse- Also return phone numbers
webhook_urlhttps://example.com/webhook- Also POST the result to this URL
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"const res = await fetch("https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks", {
headers: {
"X-Tomba-Key": process.env.TOMBA_API_KEY,
"X-Tomba-Secret": process.env.TOMBA_SECRET_KEY
}
});
const { data } = await res.json();import os, requests
res = requests.get(
"https://api.tomba.io/v1/email-finder?domain=piedpiper.com&first_name=Richard&last_name=Hendricks",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
)
data = res.json()["data"]// 02 · response
What comes back
JSON, the same in every language. Fields Tomba doesn't know are null, never guessed.
GET
/email-finderFielddata.emailstring | null- The address, or null when none is found
data.scoreinteger- Confidence from 0 to 100
data.verification.statusstring | null- valid, accept_all, invalid or unknown, with verification.date
data.full_name, data.position, data.departmentstring | null- Name, job title and team
data.typestring | null- personal or generic (a role address such as sales@)
data.linkedin, data.twitterstring | null- Public profiles
data.sources[]array | null- Up to 20 public pages where the address was found, with dates
data.accept_allboolean | null- The domain accepts mail for any address (catch-all)
data.phone_numberboolean- Tomba holds a phone number for the person
data.phone_data[]array- The numbers, when you send enrich_mobile (each as in Phone Finder)
GET /email-finder
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": []
}
}// 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: An address is returned with a status other than unknown. 6 with phone data.
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| Free | Basic | Growth | Pro | |
|---|---|---|---|---|
| Search, finder, similar, technology | 1 / 2 / 5 | 3 / 50 / 500 | 5 / 80 / 1,000 | 8 / 150 / 4,000 |
| Email verifier | 1 / 2 / 10 | 2 / 40 / 500 | 3 / 60 / 1,000 | 5 / 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
Verified email, confidence score (0-100), first name, last name, job title, department, seniority, country, LinkedIn URL, Twitter, phone number, company name, email pattern, source URLs, and verification status.
Tomba ranked #1 of 9 in its public 5,000-lead benchmark (raw data published), with 81% coverage from company websites and more valid emails than the eight other tools tested. Every result is SMTP-verified before delivery.
No. Credits only consumed for valid, deliverable results.
Yes. Direct phone numbers returned when available at no extra credit cost.
13 official SDKs: C#, Dart, Deno, Elixir, Go, Lua, Node.js, Perl, PHP, Python, R, Ruby and Rust.
Rate limits depend on your plan and the endpoint. The docs list them, and GET /v1/rate-limits returns the ones that apply to you. Response times vary by endpoint and by how hard an address is to verify, so set a generous timeout (the docs suggest up to 180 seconds) and use bulk jobs or webhooks for large volumes.
Yes. The Bulk Email Finder API processes up to 10,000 name/domain pairs per operation via CSV upload or API batch requests.
A 0-100 score based on pattern matching, source count, verification result, and data freshness. Higher scores mean higher deliverability likelihood.