// post /v1/reveal/search
Company Reveal API
Reveal complete company intelligence from any domain: industry, revenue, headcount, tech stack, social profiles, and verified decision-maker contacts via a single API call.
1 search credit
// api console
ExampleExample response from the API reference
- companies
- 1 item
- companies[0].name
- Pied Piper
- companies[0].website_url
- piedpiper.com
- companies[0].industry
- computer software
- companies[0].company_size
- 11-50
- companies[0].city
- Palo Alto
- companies[0].founded
- 2014
- companies[0].total_emails
- 48
// 01 · request
Company Search is one HTTPS request
Send the parameters with your key and secret. Every SDK, the CLI and the MCP server make this same call.
POST
/reveal/searchqueryrequired- What you are looking for, in plain language
page1- Result page
curl -X POST https://api.tomba.io/v1/reveal/search \
-H "X-Tomba-Key: $TOMBA_API_KEY" \
-H "X-Tomba-Secret: $TOMBA_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"Compression startups in California","page":1}'const res = await fetch("https://api.tomba.io/v1/reveal/search", {
method: "POST",
headers: {
"X-Tomba-Key": process.env.TOMBA_API_KEY,
"X-Tomba-Secret": process.env.TOMBA_SECRET_KEY,
"Content-Type": "application/json"
},
body: JSON.stringify({"query":"Compression startups in California","page":1})
});
const { data } = await res.json();import os, requests
res = requests.post(
"https://api.tomba.io/v1/reveal/search",
headers={
"X-Tomba-Key": os.environ["TOMBA_API_KEY"],
"X-Tomba-Secret": os.environ["TOMBA_SECRET_KEY"],
},
json={"query":"Compression startups in California","page":1},
)
data = res.json()["data"]// 02 · response
What comes back
JSON, the same in every language. Fields Tomba doesn't know are null, never guessed.
POST
/reveal/searchdata.companies[]array | null- Name, website, description, industry, size, type, founded, revenue, location, social links
data.companies[].total_emailsinteger- Addresses Tomba holds for the company
data.companies[].total_similarinteger- Similar companies Tomba knows
meta.total, meta.pagesinteger- Companies that match, and pages
meta.page, meta.limitinteger- This page and its size
meta.filtersobject- The filters Tomba read from your query
POST /reveal/search
200 OK· 1 search credit
{
"success": true,
"data": {
"companies": [
{
"name": "Pied Piper",
"description": "Middle-out compression for files and video.",
"country": "US",
"state": "California",
"city": "Palo Alto",
"street_address": "5230 Newell Road",
"postal_code": "94303",
"industry": "computer software",
"company_size": "11-50",
"type": "privately held",
"founded": "2014",
"website_url": "piedpiper.com",
"total_emails": 48,
"revenue": "",
"phone_number": false,
"linkedin_url": "https://www.linkedin.com/company/pied-piper",
"facebook_url": "",
"twitter_url": "",
"total_similar": 2
}
]
},
"meta": {
"total": 64,
"page": 1,
"limit": 10,
"pages": 7,
"filters": {
"location_state": {
"include": [
"California"
]
},
"industry": {
"include": [
"computer software"
]
}
}
}
}// 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: At least one company 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| 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 |
Scroll sideways for every column
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
A comprehensive company profile including: name, description, industry, revenue range, employee count, headquarters, tech stack, social profiles, email pattern, MX records, WHOIS data, similar companies, and domain metadata.
Company Reveal combines company enrichment with contact discovery. It returns the full company profile plus verified decision-maker emails and phone numbers: all from a single API call.
1 credit per company reveal. If no data is found for the domain, no credit is consumed: you only pay for results.
Yes. The Bulk Company Reveal API processes thousands of domains via CSV or API batch.
POST /reveal/search takes up to 5 requests a second on every plan. Every response carries rate-limit headers; see Rate limits.
Yes. Tomba only processes publicly available business data, respects opt-out requests, and applies data minimization principles.
13 official SDKs: C#, Dart, Deno, Elixir, Go, Lua, Node.js, Perl, PHP, Python, R, Ruby and Rust.
Company profiles refresh monthly, technology data quarterly, and domain/DNS information is verified in real-time on each lookup.