Apify actors
Each actor calls one Tomba endpoint for every entry in its input list and writes the results to the run's default dataset. How to start a run and what a run costs are on Apify.
How the actors run
The actors call Tomba with Tomba's own credentials, so no input takes a Tomba API key and you don't need a Tomba account.
- Parallel requests. Up to
maxConcurrencyrequests run at once, with no pacing between them. When Tomba's rate limits answer429, the request is retried. - Retries. A request that fails with
429, a5xxstatus, a network error, or a timeout is retried up tomaxRetriestimes, with exponential backoff starting at 1 second and capped at 30 seconds. ARetry-Afterheader sets the wait instead. Other errors aren't retried; the input produces an item with anerrorfield. - Cache. Successful responses are stored in a named key-value store in your Apify account,
tomba-cache-<actorId>, one per actor, and reused for identical requests (same endpoint and parameters) forcacheTtlHours. A cached result costs nothing and hascached: true. If the store can't be opened, the run continues and caches results for that run only. - Resume. Processed inputs are recorded in the
TOMBA_STATErecord of the run's default key-value store. When Apify migrates or restarts the run, it skips those inputs. - Max cost per run. Before each request, the actor checks that the run's Max cost per run leaves room for the request's charge. When it doesn't, the actor starts no new requests, lets the running ones finish, and exits. Inputs it didn't reach produce no item.
- Input clean-up. Domains are trimmed, lowercased, and stripped of
http://,https://,www., and any path. Email addresses are trimmed and lowercased. Duplicate inputs are removed before any request. - Items as they arrive. Each input's items are written to the dataset as soon as its request finishes, so an aborted run keeps the items it already produced.
Run options
Every actor accepts these inputs, under Run options in the input form.
| Input | Type | Default | Description |
|---|---|---|---|
maxConcurrency | integer, 1 to 50 | 10 | Requests that run at the same time. |
maxRetries | integer, 0 to 10 | 3 | Retries after a 429, a 5xx status, a network error, or a timeout. |
useCache | boolean | true | Reuse cached results. false sends every request to Tomba. |
cacheTtlHours | integer, 0 to 720 | 24 | How long a cached result stays valid. 0 turns off the cross-run cache; results are reused within a run. |
Charges
Apify charges the tomba-request event to your Apify account; the event price is on each actor's Store page.
- A request is charged when Tomba returns a JSON response with non-empty
dataand noerrorsobject. A negative answer is a result, so an undeliverable verification or a domain with no email addresses is charged. The "Charged when" column in Credit costs doesn't apply to the actors. - A charged request costs one event per Tomba credit in Credit costs, including the extra credits for phone data. Technology finder charges one event per domain with technologies, although the endpoint itself costs no credits.
- Error statuses, responses with empty or
nulldata, responses with anerrorsobject, responses that aren't JSON, and cached results aren't charged.
Every item has charged and cached. Items from actors whose requests can cost more than one credit also have chargedCredits, the events charged for the item, and actors that return phone data add phoneNumbers, the number of phone numbers in the item.
Real-time API
Every actor also runs in Apify Standby mode, an HTTP server that returns the items in the response instead of a dataset. Find the actor's Standby URL on its API tab in Apify, and send your Apify API token.
Code
GET /with query parameters builds the input from them; each actor's parameters are listed in its section. A list parameter can be repeated (?domain=stripe.com&domain=shopify.com) or comma-separated (?domains=stripe.com,shopify.com). Boolean parameters taketrue,false,1,0,yes, orno.POST /takes the same JSON input as a run, up to 1 MB.GET /without query parameters returns{"status": "ready", "usage": "…"}.- The response is
{"items": [...]}, with the same items a run writes to its dataset. Charges are the same as for a run.
| Status | When |
|---|---|
200 | The request was processed. Inputs without a result are items with an error field. |
400 | A query parameter, the JSON body, or the input is invalid. The error field says which. |
402 | The Standby run reached its maximum charge. Every later request gets this status. |
404 | The path isn't /. |
405 | The method isn't GET or POST. |
Run options can't be set per request: every request uses the defaults in Run options. Standby requests don't use the resume state.
Domain search
tomba-io/domain-search calls GET /v1/domain-search for each domain or company name, one results page at a time. Searches run in parallel; the pages of one search are requested one after another, starting at page, until the actor has maxEmailsPerDomain addresses, a page returns fewer than limit addresses, or the last page is reached.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
domains | array of strings | domains or companies | — | Domains to search, such as stripe.com. |
companies | array of strings | domains or companies | — | Company names to search, such as Stripe. Tomba resolves each name to a domain. |
maxEmailsPerDomain | integer, 1 to 100 | No | 10 | Addresses to collect per domain or company name. |
limit | string: 10, 20, or 50 | No | 10 | Addresses per page. Each page is charged by its limit, so a limit above maxEmailsPerDomain pays for addresses the actor drops. |
page | integer, 1 or more | No | 1 | First page to request. |
department | string | No | — | Return only people in one department, such as engineering or sales. The input form lists the accepted values. |
country | string | No | — | Two letters, such as US or gb; lowercase is converted to uppercase. Returns only people in that country. |
enrichMobile | boolean | No | false | Return each person's phone numbers in emails[].phone_data. Addresses with phone data cost extra; see Credit costs. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url on every page request; see Webhooks. Cached results aren't sent again. |
includeCompanyInfo | boolean | No | true | Include organization in the item. |
outputFormat | string: detailed or simple | No | detailed | Saved in the SUMMARY record. It doesn't change the output. |
Each domain or company name produces one item with the input (domain or company), organization (see Company), emails (see Person), meta from the last page, pages, chargedRequests (pages charged), chargedCredits, phoneNumbers, charged, and cached (true when every page came from the cache). For a company name, the item also has the domain Tomba resolved, when the response reports one. When the first page returns no result or fails, the item has the input and an error field; when a later page does, the item keeps the addresses already collected. Batch runs also save the input counts, request counts, and settings as a SUMMARY record in the default key-value store.
Real-time API parameters: domain, domains, company, companies, maxEmailsPerDomain, includeCompanyInfo, page, limit, department, country, enrichMobile, webhookUrl.
Email finder
tomba-io/email-finder calls GET /v1/email-finder once per request object.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
requests | array of objects, 1 to 1,000 | Yes | — | Each object has domain or company (a company name), and fullName or both firstName and lastName. |
maxResults | integer, 1 to 1,000 | No | 50 | Requests to process. Requests after this number are skipped. |
enrichMobile | boolean | No | false | Return the person's phone numbers in phone_data. A result with phone data costs extra; see Credit costs. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url; see Webhooks. |
Each request produces one item: the response's data fields (see Person) plus the input as domain, firstName, lastName, fullName, and inputCompany (the input company, since company is a response field), source set to tomba_email_finder, phoneNumbers, chargedCredits, charged, and cached. When no address is found or the request fails, the item has the input fields and an error field instead of the data fields. A request without the required fields isn't sent to Tomba and produces an item with an error field.
Real-time API parameters: domain, company, firstName or first_name, lastName or last_name, fullName or full_name, enrichMobile, webhookUrl, maxResults. A GET request makes one search.
Author finder
tomba-io/author-finder calls GET /v1/author-finder once per URL.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
urls | array of strings | Yes | — | Article URLs. |
maxResults | integer, 1 to 1,000 | No | 50 | URLs to process. URLs after this number are skipped. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url; see Webhooks. |
Each URL produces one item. When an author is found, it is the response's data object (see Author finder) plus input_url, source set to tomba_author_finder, chargedCredits, charged, and cached. When no author is found or the request fails, the item has input_url, email set to null, and an error field.
Real-time API parameters: url, urls, webhookUrl, maxResults.
Email enrichment
tomba-io/email-enrichment calls GET /v1/enrich once per email address.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
emails | array of strings, 1 to 1,000 | Yes | — | Email addresses to enrich. |
maxResults | integer, 1 to 1,000 | No | 50 | Addresses to process. Addresses after this number are skipped. |
enrichMobile | boolean | No | false | Return the person's phone numbers in phone_data. A result with phone data costs extra; see Credit costs. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url; see Webhooks. |
Each address produces one item: the response's data fields (see Person) plus email, source set to tomba_email_enrichment, phoneNumbers, chargedCredits, charged, and cached. When no person is found or the request fails, the item has email, source, and an error field instead of the data fields.
Real-time API parameters: email, emails, enrichMobile, webhookUrl, maxResults.
Email verifier
tomba-io/email-verifier calls GET /v1/email-verifier once per email address.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
emails | array of strings, 1 to 1,000 | Yes | — | Email addresses to verify. |
maxResults | integer, 1 to 1,000 | No | 50 | Stop after this many addresses have a verification result. Items with an error field don't count, and requests already running still produce items. |
enrichMobile | boolean | No | false | Return the phone numbers linked to the address in phone_data. Each phone number costs extra; see Credit costs. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url; see Webhooks. |
Each address produces one item with the response's email object (see Email verifier attributes), sources, input (the address you sent), phoneNumbers, chargedCredits, charged, and cached; with enrichMobile, also phone_data. When the request fails or returns no data, the item has input and an error field.
Real-time API parameters: email, emails, enrichMobile, webhookUrl, maxResults.
LinkedIn finder
tomba-io/linkedin-finder calls GET /v1/linkedin once per profile URL.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
linkedinUrls | array of unique strings, 1 to 1,000 | Yes | — | Profile URLs that contain linkedin.com/in/, such as https://www.linkedin.com/in/jane-doe, https://linkedin.com/in/jane-doe, or https://uk.linkedin.com/in/jane-doe?trk=public. Company pages are rejected. |
maxResults | integer, 1 to 10,000 | No | 50 | URLs to process. URLs after this number are skipped. |
enrichMobile | boolean | No | false | Return the profile's phone numbers in phone_data. A result with phone data costs extra; see Credit costs. |
full | boolean | No | false | Return every address Tomba has stored for the profile instead of the best one, one item per address. Each address is charged; see Credit costs. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url; see Webhooks. |
When an address is found, each address produces one item: the response's data (see Person) plus linkedin_url, source set to tomba_linkedin_finder, phoneNumbers, chargedCredits, charged, and cached. With full, the request's charge is split across its items' chargedCredits. When no address is found or the request fails, the item has email set to an empty string, linkedin_url, source, and an error field.
Real-time API parameters: url, urls, linkedinUrl, linkedinUrls, enrichMobile, full, webhookUrl, maxResults.
Phone finder
tomba-io/phone-finder calls GET /v1/phone-finder once per search object.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
searches | array of objects | Yes | — | Each object has email, domain, or linkedin (a LinkedIn profile URL). All fields in an object are sent together, and a search that includes domain costs fewer credits; see Credit costs. Objects with none of the three fields are skipped without an item. |
maxResults | integer, 1 to 1,000 | No | 50 | Stop after this many valid phone numbers are found. Requests already running still produce items. |
full | boolean | No | false | Sent to Tomba as full=true on every search. |
webhookUrl | string | No | — | URL starting with http:// or https://, sent to Tomba as webhook_url on every search; see Webhooks. |
Each search produces one item: the input email, domain, and linkedin (null when not set), the response's data fields (see Phone), source, chargedCredits, charged, and cached. Here source is an object with search_type (email, linkedin, or domain, in that order of precedence) and search_value. When the number isn't valid, the item also has an error field. When the request fails or returns no data, the item has the input fields, valid set to null, and an error field.
Real-time API parameters: email, domain, linkedin, full, webhookUrl, maxResults. A GET request makes one search.
Phone validator
tomba-io/phone-validator calls GET /v1/phone-validator once per number.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
phoneNumbers | array of objects, 1 to 1,000 | Yes | — | Each object has phoneNumber (10 to 20 characters, required) and countryCode (two letters, such as GB). Set countryCode for numbers written without a + country prefix, or the request fails. Numbers with the same digits and country code are validated once. |
maxResults | integer, 1 to 10,000 | No | 50 | Stop after this many numbers have a validation result. Requests already running still produce items. |
Each number produces one item with phone_number (your input), input_country_code, source set to tomba_phone_validator, charged, and cached, plus these fields from the response (see Phone): valid, country_code, carrier, line_type, national_format (from local_format), international_format (from intl_format), e164_format, rfc3966_format, location (the region's name), and timezone (from timezones). The country_name column stays empty because the response has no country name. When the request fails or returns no data, the item has valid set to false and an error field.
Real-time API parameters: phone (repeated or comma-separated; a leading + left unencoded in the URL is accepted), countryCode or country_code (applies to every number), maxResults.
Email count
tomba-io/email-count calls GET /v1/email-count once per domain.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
domains | array of strings | Yes | — | Domains to count addresses for, such as stripe.com. |
maxResults | integer, 1 to 1,000 | No | 50 | Stop after this many domains have a count. Items with an error field don't count, and requests already running still produce items. |
Each domain produces one item: the response's data fields (see Email count) plus domain, source set to tomba_email_count, charged, and cached. When the request fails or returns no data, the item has domain, source, and an error field.
Real-time API parameters: domain, domains, maxResults.
Similar finder
tomba-io/similar-finder calls GET /v1/similar once per domain and reads the first page of results.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
domains | array of unique strings, 1 to 1,000 | Yes | — | Domains, such as stripe.com, bbc.co.uk, or blog.stripe.com. URLs such as https://www.stripe.com/pricing are reduced to the domain. |
maxResults | integer, 1 to 10,000 | No | 50 | Maximum number of items. A domain's results are cut at the limit, and a domain whose request finishes after the limit is reached produces no item. |
Each similar domain produces one item with input_domain, similar_domain and website_url (both the similar company's domain), company_name, industries, source set to tomba_similar_finder, charged, and cached (see Similar domains). A domain with no results, or a failed request, produces one item with similar_domain set to null and an error field.
Real-time API parameters: domain, domains, maxResults.
Technology finder
tomba-io/technology-finder calls GET /v1/technology once per domain.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
domains | array of unique strings, 1 to 1,000 | Yes | — | Domains, such as stripe.com, bbc.co.uk, or blog.stripe.com. URLs such as https://www.stripe.com/pricing are reduced to the domain. |
maxResults | integer, 1 to 10,000 | No | 50 | Maximum number of items. A domain's results are cut at the limit, and a domain whose request finishes after the limit is reached produces no item. |
Each technology produces one item with input_domain, technology_slug, technology_name, technology_icon, technology_website, technology_description, category_id, category_slug, and category_name (from the first category), categories (the names of all its categories), source set to tomba_technology_finder, charged, and cached (see Technology). A domain with no technologies, or a failed request, produces one item with technology_name set to null and an error field.
Real-time API parameters: domain, domains, maxResults.
Person enrichment
tomba-io/clearbit-person calls GET /v1/people/find once per email address. The response comes from Tomba's data, in a Clearbit-compatible format.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
emails | array of strings | Yes | — | Email addresses to enrich. |
maxResults | integer, 1 to 1,000 | No | 50 | Addresses to process. Addresses after this number are skipped. |
Each address produces one item. With a match, it is the response's data object (see Person fields) plus email, source set to tomba_person_enrichment, charged, and cached. Without a match, or when the request fails, the item has email, source, and an error field.
Real-time API parameters: email, emails, maxResults.
Company enrichment
tomba-io/clearbit-company calls GET /v1/companies/find once per domain. The response comes from Tomba's data, in a Clearbit-compatible format.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
domains | array of strings | Yes | — | Company domains, such as stripe.com. |
maxResults | integer, 1 to 1,000 | No | 50 | Domains to process. Domains after this number are skipped. |
Each domain produces one item. With a match, it is the response's data object (see Company fields) plus domain, source set to tomba_company_enrichment, charged, and cached. Without a match, or when the request fails, the item has domain, source, and an error field.
Real-time API parameters: domain, domains, maxResults.
Combined enrichment
tomba-io/clearbit-combined calls GET /v1/combined/find once per email address and returns the person and their company together. The response comes from Tomba's data, in a Clearbit-compatible format.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
emails | array of strings | Yes | — | Email addresses to enrich. |
maxResults | integer, 1 to 1,000 | No | 50 | Addresses to process. Addresses after this number are skipped. |
Each address produces one item. With a match, it is the response's data object, with person and company (see Combined fields), plus email, source set to tomba_enrichment, chargedCredits, charged, and cached. Without a match, or when the request fails, the item has email, source, and an error field.
Real-time API parameters: email, emails, maxResults.
Company search
tomba-io/company-search calls POST /v1/reveal/search once per results page. Pages are requested one after another, starting at page, and each page with companies is charged one event. Paging stops when the actor has maxResults companies, reaches the last page, or gets a page shorter than the page size, an empty page, or an error.
| Input | Type | Required | Default | Description |
|---|---|---|---|---|
query | string | query or filters | — | Natural-language search, such as software companies in Berlin. |
filters | object | query or filters | — | Filters keyed by company, location_country, location_city, location_state, industry, size, type, keywords, founded, technologies, similar, revenue, sic, or naics, each with include and exclude arrays. See the endpoint reference for accepted values. |
source | array of strings | No | — | Company fields to return. Empty returns all fields. |
page | integer, 1 or more | No | 1 | First results page to request. |
maxResults | integer, 1 to 100,000 | No | 100 | Maximum number of companies. |
Each company produces one item with the company fields from the response, source set to tomba_company_search, charged, and cached. When the first page returns no companies or fails, the run produces one item with query, page, and an error field; when a later page does, the actor keeps the companies it already has. Batch runs record their progress in the COMPANY_SEARCH_PROGRESS record of the default key-value store, so a migrated or restarted run continues from the next page.
Real-time API parameters: query, filters (a JSON object, URL-encoded), source (repeated or comma-separated), page, maxResults.