Frequently asked questions
Each answer links to the page that has the full details.
How do I get an API key and secret?
Create an account, then copy a key and your secret from the API keys page of the dashboard. Quickstart walks through it, and Authentication shows how to send them.
Do API keys expire?
Yes. Every key has an expiry date, and a request with an expired key fails with the error type api_key_expired. Key expiry gives the lifetime, and Rotate keys shows how to replace a key without downtime.
When does a request use credits?
Most endpoints charge only when a request succeeds and returns a result, and most repeats of the same request within your usage window are free. Credit costs lists what each endpoint costs and when it's charged.
Do unused credits carry over?
Plan credits don't: they reset at the start of each usage window. Credits from a credit pack stay available until the pack expires. See Quotas.
How do I check how many credits I have left?
Open Usage in the dashboard, or call GET /v1/me. Check usage lists the response fields and headers that report your balance.
What does a 429 response mean?
You hit a rate limit, or used up your email count or sources credits. Handle 429 responses explains how to tell the two apart and when to retry.
Can I get a credit back for an address that bounced?
Yes, for a hard bounce. Report the address with POST /v1/flag and the reason hard_bounce, and Tomba refunds a credit after it confirms the report. See Refunds for incorrect data and the Data quality guarantee.
Can I get a refund on my subscription?
Subscription refunds follow the Refund Policy in the Terms of Service.
What do status and result mean in a verification?
result is the deliverability verdict, and status is the detailed outcome of the check. Status values and Result values list every value and what to do with it.
Where does Tomba's data come from?
From public web sources, such as company websites and published articles, and from addresses that Tomba generates from each company's email format and checks against its mail server. See Data sources and coverage.
How can someone remove their data from Tomba?
With the Claim tool, or by emailing privacy@tomba.io. Once the request is confirmed, Tomba stops returning the data, and requests for it return status 451. See Data removal.
Can I use Tomba without calling the REST API directly?
Yes. Use the SDKs, the Tomba CLI, the MCP server for AI assistants, integrations such as Zapier and n8n, or the Google Sheets and Excel add-ons.