X-Tomba-Key and X-Tomba-Secret. Set the key as the plugin key and pass the secret as apiSecret, or store both on the account.
Things to know:
- Lookups cost credits. Each call draws on a plan allowance.
account.getreports what is left for the current usage window, andaccount.rateLimitsreports the per-route limits. - A miss is a success. When no address is found, the finder answers 200 with
data.email: nulland a score of 0. That is a legitimate answer to check, not an error. - A webmail domain is an error. A request against
gmail.comfails with 400 and typeunknown_record, because Tomba refuses disposable and webmail domains rather than returning nothing. - 402 means an empty balance. Nothing is charged and no retry helps.
finder.phonecosts more than the other lookups. - 451 means the person opted out. Tomba withholds their data permanently at their request, so the call is not retried.
- Rate limits name their window. The 429 message says whether the per-second, per-minute or daily limit was hit, and
Retry-Aftersays when to retry. A per-second or per-minute 429 is retried up to three times; a used-up daily limit or count/sources balance is not retried. On the Free plan most lookups allow 5 calls a day per route. - Not included. Bulk jobs, lead management, API key management and scraper campaigns have their own routes and are not part of this plugin.
- 22 typed API operations
Setup
1
Install
2
Add the plugin
corsair.ts
multiTenancy: true, scope calls with corsair.withTenant(id). See Quick start for KEK + Hub keys, and Multi-tenancy for account isolation.3
Choose authentication
- API Key (Recommended)
Store the Tomba API key before the first call: More: API Key
pnpm corsair setup --plugin=tomba --tenant=acme api_key=<your-key> (leave out --tenant without multiTenancy), or pass it as key in the plugin options. With Hub, each tenant enters their own key on the connect page. See API key auth.4
Connect a tenant
Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see Connect / OAuth.
Example API calls
Find one person work emailWhat’s next
API reference
Every
tomba.api.* operation with input and output types.Connect / OAuth
createLink, Hub delivery, and tenant connect flows.
Use with agents
Expose this plugin’s operations as MCP tools.