Local HTTP server
tomba serve runs an HTTP server that forwards each request to the Tomba API with the credentials the CLI is signed in with. Use it to call Tomba from local scripts and tools, or to back Slack slash commands. CLI versions before 1.2.3 name this command tomba http.
The server has no authentication, listens on all IPv4 interfaces, and
accepts cross-origin requests from any website. Anyone who can reach the
port, including web pages open in your browser, can spend your credits, read
your API secret from GET /whoami, and list, create, or delete your API
keys through /keys. Block the port at your firewall and stop the server
when you're not using it. To expose routes to the internet, put a reverse
proxy in front that forwards only the routes you need, as shown in Slack
slash commands.
Start the server
Code
| Flag | Short | Type | Default | Description |
|---|---|---|---|---|
--port | -p | int | 3000 | Port to listen on. The server listens on all IPv4 interfaces (0.0.0.0); there is no option to listen on localhost only. |
The server reads your credentials once, at startup, in the order described in Authentication. It runs in the foreground and logs each request to standard output with the time, client IP, status, latency, method, path, and query string. Stop it with Ctrl+C. If the port is already in use, tomba serve exits immediately without an error message; choose another port with --port.
Each request to the server makes one API request, billed and rate-limited as described in Credit costs and Rate limits.
The Linux packages install a systemd unit, tomba.service, that runs tomba serve as www-data and is enabled at boot.
Send a request
Code
The lookup routes accept a JSON body or form fields. The /people/find, /companies/find, and /combined/find routes, and the lead, lead list, attribute, key, and flag routes, accept JSON only.
Routes
Lookups
| Method and path | Body fields | Calls |
|---|---|---|
POST /search | domain | GET /v1/domain-search, first page |
POST /finder | domain, plus first_name and last_name or full_name; enrich_mobile | GET /v1/email-finder |
POST /author | url | GET /v1/author-finder |
POST /enrich | email, enrich_mobile | GET /v1/enrich |
POST /linkedin | url, enrich_mobile | GET /v1/linkedin |
POST /verify | email | GET /v1/email-verifier |
POST /sources | email | GET /v1/email-sources |
POST /count | domain | GET /v1/email-count |
POST /status | domain | GET /v1/domain-status |
POST /format | domain | GET /v1/email-format |
POST /location | domain | GET /v1/location |
POST /autocomplete | query | GET /v1/domain-suggestions |
POST /similar | domain | GET /v1/similar |
POST /technology | domain | GET /v1/technology |
POST /phone-finder | One of email, domain, or linkedin; full | GET /v1/phone-finder |
POST /phone-validator | phone, country_code | GET /v1/phone-validator |
POST /reveal | query, or the arrays country, industry, and size; page | POST /v1/reveal/search |
POST /people/find | email | GET /v1/people/find |
POST /companies/find | domain | GET /v1/companies/find |
POST /combined/find | email | GET /v1/combined/find |
For example, a company search with filters:
Code
Account and data
| Method and path | Calls |
|---|---|
GET /whoami | GET /v1/me. The response includes your API secret. |
GET /usage | GET /v1/usage |
GET /logs | GET /v1/logs, first page |
GET /keys, POST /keys | List or create API keys |
GET /keys/{id}, DELETE /keys/{id} | Get or delete a key |
PUT /keys/{id} | Calls PUT /v1/keys/{id}/reset, which the API doesn't have, so it returns 500. Rotate keys with the API instead. |
GET /flag, POST /flag | List or create flags |
GET /leads, POST /leads | List or create leads |
GET /leads/{id}, PUT /leads/{id}, DELETE /leads/{id} | Get, update, or delete a lead |
GET /leads_lists, POST /leads_lists | List or create lead lists |
GET /leads_lists/{id}, PUT /leads_lists/{id}, DELETE /leads_lists/{id} | Get, update, or delete a lead list |
GET /attributes, POST /attributes | List or create lead attributes |
GET /attributes/{id}, PUT /attributes/{id}, DELETE /attributes/{id} | Get, update, or delete an attribute |
GET / redirects to the Tomba website.
Responses
A successful request returns status 200 with the Tomba API's response. Errors use the server's own format, not the API's:
| Status | Body | When |
|---|---|---|
400 | {"status": "error", "message": "..."} | A lookup's input is missing or malformed. |
401 | {"status": "error", "message": "invalid KEY or SECRET"} | The API call failed on /whoami, /usage, /logs, or a lookup route not listed under 500, for any reason: this includes rate limits (429) and exhausted credits (402), not only bad credentials. |
404 | {"status": "error", "message": "..."} | search, finder, author, enrich, linkedin, or count found nothing, or verify got an address at a webmail or disposable email domain. |
222 | {"status": "error", "message": "..."} | verify couldn't complete the check because the recipient's mail server responded unexpectedly. |
500 | {"error": "error: <HTTP status>, status code: <code>"} | The API call failed on /format, /location, /autocomplete, /people/find, /companies/find, /combined/find, or a lead, lead list, attribute, key, or flag route. |
Because a 401 hides the API's status, run the same lookup with the CLI, such as tomba verify --target jane.doe@stripe.com, to see it; see Status codes.