Tomba integration: operations for AI agents
Tomba connects to Type.com as an integration. This page lists the 75 operations documented for Claude and Codex in Type.com: 48 read, 17 write, 10 destructive.
About Tomba
Tomba vendor API references, subject to account permissions.
Categories: Sales & CRM
How to connect Tomba to Type.com
- Access
- Organization connection: one shared account for the workspace.
To add the connection, follow the steps in Space connections.
Documented operations
75 operations. Your connection's permissions determine which operations are available. API references describe the vendor surface; they do not expand your connection's credentials or access.
75 operations listed.
- Read
Get Account
Get Account GET https://api.tomba.io/v1 /me X-Tomba-Key (header) + X-Tomba-Secret (header) Returns your account, your plan, and your credit usage in the current usage window. requests.domains , requests.verifications , and requests.count hold your search, verification, and email count allowances ( available ) and what you've used ( used ). The remaining balance is available minus used . issued and expired bound the current usage window. expired_subscription is when the subscription period ends. pricing.available_searches and pricing.available_verifications include your unused credit-pack credits, which addon_credits lists separately. secret_t
GET /me - Read
Retrieve API Usage
Retrieve API Usage GET https://api.tomba.io/v1 /usage X-Tomba-Key (header) + X-Tomba-Secret (header) Returns your daily credit usage over a range of days, one row per user and day, with totals for the range. duration sets the range: from that many days ago through today. Rows exist only for days with charged credits. scope=team returns the rows of every member of your workspace, and scope=member the rows of one member. Both need the workspace owner or admin role. A workspace owner's rows also include the credits that members used on most endpoints, because those count against the owner's pool. With scope=team , those credits appear in both th
GET /usage - Read
Retrieve API Logs
Retrieve API Logs GET https://api.tomba.io/v1 /logs X-Tomba-Key (header) + X-Tomba-Secret (header) Returns your billable lookups, newest first, with what each one cost. Only requests to endpoints that cost credits, and that returned 200 with a result, are logged. Repeats of a lookup already charged in the current usage window appear with cost 0 . Failed requests, lookups without a result, and free endpoints aren't logged. In a workspace, the response includes the rows of every member; member_id narrows it to one member. data is null when no row matches. Call this endpoint with an API key and secret. OAuth access tokens aren't accepted and get
GET /logs - Read
Retrieve a Single API Log
Retrieve a Single API Log GET https://api.tomba.io/v1 /logs/{logId} X-Tomba-Key (header) + X-Tomba-Secret (header) Returns one row of GET /logs by its id . In a workspace, you can read the rows of every member. The API also matches logId against the row's request_id , but rows logged by the current API don't record one, so use id . Call this endpoint with an API key and secret. OAuth access tokens aren't accepted and get 401 . Retrieve a Single API Log
GET /logs/{logId} - Read
Retrieve rate limits
Retrieve rate limits GET https://api.tomba.io/v1 /rate-limits X-Tomba-Key (header) + X-Tomba-Secret (header) Returns, for every rate-limited route, the limits that apply to your account and the requests counted against them in the current minute and day. The limits come from your plan, raised by any credit pack that still has credits. 0 means unlimited. In a workspace, members get the owner's limits, and the usage counts cover the whole workspace. Every API key, OAuth app, and member of an account or workspace shares these counters. Daily counts reset at 00:00 UTC. pricing.rate_limits in GET /me shows your own plan's limits; this endpoint sho
GET /rate-limits - Read
List bulk jobs
List bulk jobs GET https://api.tomba.io/v1 /bulk/{type} X-Tomba-Key (header) + X-Tomba-Secret (header) List the jobs of a type, limit per page, sorted by job ID. Jobs are shared by all members of a workspace. Archived jobs are listed only with archived=true , and deleted jobs never. List bulk jobs
GET /bulk/{type} - Read
Get a bulk job
Get a bulk job GET https://api.tomba.io/v1 /bulk/{type}/{id} X-Tomba-Key (header) + X-Tomba-Secret (header) Get a job by ID, with its options in config , its results in metrics , and, once it is billed, the first result rows in preview . Get a bulk job
GET /bulk/{type}/{id} - Read
Get bulk job progress
Get bulk job progress GET https://api.tomba.io/v1 /bulk/{type}/{id}/progress X-Tomba-Key (header) + X-Tomba-Secret (header) Get a job's status, progress, estimated time left, and results so far. The fields are at the top level of the response, not in data . Poll until status is completed , failed , or cancelled , or use a webhook instead. Get bulk job progress
GET /bulk/{type}/{id}/progress - Read
Download bulk job results
Download bulk job results GET https://api.tomba.io/v1 /bulk/{type}/{id}/download X-Tomba-Key (header) + X-Tomba-Secret (header) Download a result file of a completed job as CSV. file selects it: full (the default), valid , or not_found . A job without a file of that kind returns 404 , and a job past its expired_at returns 409 . The first successful download charges the job's credits, shown in metrics.credits ; later downloads of any file are free. If your balance is lower than the cost at the first download, the response is 429 and nothing is charged. See Billing . Each job can be downloaded 25 times a day, and a domain export 30 times. Downl
GET /bulk/{type}/{id}/download - Read
Estimate bulk job credits
Estimate bulk job credits GET https://api.tomba.io/v1 /bulk/{type}/{id}/estimate X-Tomba-Key (header) + X-Tomba-Secret (header) Get the credits a job costs, and whether your balance covers them. Before the job completes, basis is upper_bound : the cost if every row returned the maximum. Once it completes, basis is exact : what the first download charges. Estimate bulk job credits
GET /bulk/{type}/{id}/estimate - Read
Get bulk job history
Get bulk job history GET https://api.tomba.io/v1 /bulk/{type}/{id}/history X-Tomba-Key (header) + X-Tomba-Secret (header) List a job's events, oldest first: creation, launch, start, end, retries, downloads, renames, archiving, and webhook deliveries. Get bulk job history
GET /bulk/{type}/{id}/history - Read
List bulk types
List bulk types GET https://api.tomba.io/v1 /bulk/types X-Tomba-Key (header) + X-Tomba-Secret (header) List every bulk type with its input fields and the header names detected for them, its options, row limit, daily limits, result files, and metrics distributions. List bulk types
GET /bulk/types - Read
Get bulk statistics
Get bulk statistics GET https://api.tomba.io/v1 /bulk/stats X-Tomba-Key (header) + X-Tomba-Secret (header) Get the bulk activity of your account, or of your workspace: jobs created by status, rows processed, results, and credits billed, in total, per type, and per day. The period is the last 30 days unless you set from and to , and is at most one year. Get bulk statistics
GET /bulk/stats - Read
Get the bulk webhook secret
Get the bulk webhook secret GET https://api.tomba.io/v1 /bulk/webhook-secret X-Tomba-Key (header) + X-Tomba-Secret (header) Get the key your bulk job events are signed with. It is created on first use, or when you first create a job with webhook_url . See Bulk job events . Get the bulk webhook secret
GET /bulk/webhook-secret - Read
Domain status
Domain status GET https://api.tomba.io/v1 /domain-status Tells you whether a domain, or the domain of an email address, belongs to a webmail provider such as Gmail or to a disposable email provider. The endpoint needs no API key, isn't charged, and isn't rate-limited. Send domain or email . The response is a flat object, not wrapped in data , and repeats the domain or email you sent. A value that fails validation returns 200 with {"webmail": false, "disposable": true} . Domain status
GET /domain-status - Read
Similar
Similar GET https://api.tomba.io/v1 /similar X-Tomba-Key (header) + X-Tomba-Secret (header) Returns companies similar to a domain, such as competitors, 25 per page. When Tomba has the domain on record but no similar companies stored, it looks them up live before it responds, except on the Free plan. data is null when there are no similar companies. The response always has up to 25 companies per page, whatever limit you send; limit only changes the credit cost. See Credits and usage . Similar
GET /similar - Read
Technology
Technology GET https://api.tomba.io/v1 /technology X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the technologies detected on a domain's website, such as its analytics, live chat, and payment tools, with their categories. When Tomba hasn't analyzed the domain before, it detects them live before it responds, except on the Free plan. data is null when Tomba has no technology data for the domain. A live detection that fails returns 500 with type internal_error . The request needs a positive search balance; see Credits and usage . Technology
GET /technology - Read
Get domain suggestions
Get domain suggestions GET https://api.tomba.io/v1 /domain-suggestions X-Tomba-Key (header) + X-Tomba-Secret (header) Returns up to five companies whose name or domain matches your query, with their domain and the number of email addresses Tomba has for it. Use it to turn a company name into a domain before a domain search. The number of suggestions is fixed at five. This endpoint isn't charged. When nothing matches, data is an empty array; if the lookup fails, data is null . Get domain suggestions
GET /domain-suggestions - Read
Email Sources
Email Sources GET https://api.tomba.io/v1 /email-sources X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the public web pages where Tomba found an email address, with when it was first and last seen on each. When Tomba has no sources for the address, the response has status 201 and an empty data array. This endpoint uses the sources balance. Only a 200 response is charged; when the balance is used up it returns 429 . See Credits and usage . Email Sources
GET /email-sources - Read
Company API
Company API GET https://api.tomba.io/v1 /companies/find X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the company behind a domain in Clearbit's Company API format: name, description, location, industry codes, social handles, size, revenue, and technologies. Fields that Tomba doesn't fill are always null ; see Clearbit-compatible enrichment . When there's no match, the response has status 200 with an errors object instead of data : type not_found (code 404 ) when Tomba has no record of the domain, and params_invalid (code 422 ) for a disposable or webmail domain. Check for errors before you read data . See Credits and usage for when a
GET /companies/find - Read
Person API
Person API GET https://api.tomba.io/v1 /people/find X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the person behind an email address in Clearbit's Person API format: name, location, employment, and social profiles. Fields that Tomba doesn't fill are always null ; see Clearbit-compatible enrichment . For Tomba's own format, use Email Enrichment . When there's no match, the response has status 200 with an errors object instead of data : type not_found (code 404 ) when Tomba has no data for the address, and params_invalid (code 422 ) for a disposable or webmail address. Check for errors before you read data . See Credits and usage for w
GET /people/find - Read
Combined API
Combined API GET https://api.tomba.io/v1 /combined/find X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the person behind an email address and the company behind its domain in one call, in Clearbit's format: data.person has the Person API fields and data.company the Company API fields. When Tomba has no record of the domain, every company field is null and meta.email is empty. When there's no match for the person, the response has status 200 with an errors object instead of data : type not_found (code 404 ) when Tomba has no data for the address, and params_invalid (code 422 ) for a disposable or webmail address. Check for errors befor
GET /combined/find - Read
Domain Search
Domain Search GET https://api.tomba.io/v1 /domain-search X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the company behind a domain and one page of the email addresses Tomba has for it, with each person's name, job title, department, and verification status. A domain with no known addresses, and a disposable or webmail domain such as gmail.com , returns 200 with an empty data.emails array. The credit cost depends on limit , not on the number of addresses returned; see Credits and usage . Domain Search
GET /domain-search - Read
Email Finder
Email Finder GET https://api.tomba.io/v1 /email-finder X-Tomba-Key (header) + X-Tomba-Secret (header) Finds a person's professional email address from their name and their company's domain or name. Tomba returns a stored address when it has one; otherwise it generates candidate addresses and checks them against the company's mail servers. When no address is found, the response is still 200 and data.email is null . A disposable or webmail domain, such as gmail.com , fails with 400 and type unknown_record . See Credits and usage for when a request is charged. Email Finder
GET /email-finder - Read
Email Count
Email Count GET https://api.tomba.io/v1 /email-count X-Tomba-Key (header) + X-Tomba-Secret (header) Returns how many email addresses Tomba has for a domain, by email type, department, and seniority. Use it to size a domain before a domain search. An unknown, webmail, or disposable domain returns 0 in every count. This endpoint uses the email count balance, and every successful call is charged; when the balance is used up it returns 429 . See Credits and usage . Email Count
GET /email-count - Read
Email Format
Email Format GET https://api.tomba.io/v1 /email-format X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the formats that a domain's email addresses follow, such as {first}.{last} , with the share of known addresses that use each one. data is an empty array when Tomba has no formats for the domain. This endpoint uses the email count balance, and every successful call is charged, including one with an empty result; when the balance is used up it returns 429 . See Credits and usage . Email Format
GET /email-format - Read
Location
Location GET https://api.tomba.io/v1 /location X-Tomba-Key (header) + X-Tomba-Secret (header) Returns, for each country, how many of a domain's email addresses belong to people in that country. To list the addresses for one country, pass its code to domain search in country . data is an empty array when Tomba has no location data for the domain. This endpoint uses the email count balance, and every successful call is charged, including one with an empty result; when the balance is used up it returns 429 . See Credits and usage . Location
GET /location - Read
Author Finder
Author Finder GET https://api.tomba.io/v1 /author-finder X-Tomba-Key (header) + X-Tomba-Secret (header) Finds the email address of the author of an article or blog post from its URL. Tomba reads the page, identifies the author, and returns their address with the article and every author candidate in data.info . When no address is found, the response is still 200 : data.email is null , and data.info is returned if the page could be read. See Credits and usage for when a request is charged. Author Finder
GET /author-finder - Read
Linkedin Finder
Linkedin Finder GET https://api.tomba.io/v1 /linkedin X-Tomba-Key (header) + X-Tomba-Secret (header) Finds the professional email address of the person behind a LinkedIn profile URL. Tomba returns a stored address when it has one; otherwise it may read the profile and search for the address live. When no address is found, the response is still 200 and data.email is null . See Credits and usage for when a request is charged. Linkedin Finder
GET /linkedin - Read
Email Enrichment
Email Enrichment GET https://api.tomba.io/v1 /enrich X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the person behind an email address, with their name, company, job title, social profiles, and the address's verification status, in Tomba's own format. For Clearbit's format, use the Person API . When Tomba has no data for the address, the response is still 200 : data.email is null , and data.disposable and data.webmail describe the address's domain. See Credits and usage for when a request is charged. Email Enrichment
GET /enrich - Read
List My Flags
List My Flags GET https://api.tomba.io/v1 /flag X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the reports you submitted, with their review status and any credits returned. Only your own reports are listed, not your workspace's. GET /flag is limited to 10 requests per minute per IP address; failed requests don't count. It also accepts an OAuth 2.0 access token, with any scope. List My Flags
GET /flag - Read
Retrieve API Keys
Retrieve API Keys GET https://api.tomba.io/v1 /keys X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the API keys of your workspace: yours and every other member's, including their full key values. Without a workspace, returns your own keys. The response holds at most 50 keys, oldest first. Limited to 100 requests per minute. Also accepts an OAuth 2.0 access token with the account scope. Retrieve API Keys
GET /keys - Read
Retrieve a Single API Key
Retrieve a Single API Key GET https://api.tomba.io/v1 /keys/{keyId} X-Tomba-Key (header) + X-Tomba-Secret (header) Returns one API key of your workspace, including its value. After rotating a key with PUT , read its new value here. Limited to 100 requests per minute for each key ID. Also accepts an OAuth 2.0 access token with the account scope. Retrieve a Single API Key
GET /keys/{keyId} - Read
Retrieve Lead Attributes
Retrieve Lead Attributes GET https://api.tomba.io/v1 /attributes X-Tomba-Key (header) + X-Tomba-Secret (header) Returns up to 25 custom lead attributes of your workspace, or your own attributes when you aren't in a workspace. There's no pagination. Use an attribute's identifier as the key when you set its value in a lead's attributes . Also accepts an OAuth 2.0 access token with the leads scope. Retrieve Lead Attributes
GET /attributes - Read
Retrieve a Single Lead Attribute
Retrieve a Single Lead Attribute GET https://api.tomba.io/v1 /attributes/{attributeId} X-Tomba-Key (header) + X-Tomba-Secret (header) Confirms that an attribute exists in your workspace. Only id is filled in: the other fields come back as empty strings, 0 , and zero timestamps. To read an attribute's name, identifier, and type, use GET /attributes . Also accepts an OAuth 2.0 access token with the leads scope. Retrieve a Single Lead Attribute
GET /attributes/{attributeId} - Read
Retrieve Leads Lists
Retrieve Leads Lists GET https://api.tomba.io/v1 /leads_lists X-Tomba-Key (header) + X-Tomba-Secret (header) Returns up to 25 lead lists of your workspace, or your own lists when you aren't in a workspace. There's no pagination. Also accepts an OAuth 2.0 access token with the leads scope. Retrieve Leads Lists
GET /leads_lists - Read
Retrieve a Single Leads List
Retrieve a Single Leads List GET https://api.tomba.io/v1 /leads_lists/{listId} X-Tomba-Key (header) + X-Tomba-Secret (header) Returns one lead list of your workspace. Also accepts an OAuth 2.0 access token with the leads scope. Retrieve a Single Leads List
GET /leads_lists/{listId} - Read
Retrieve Leads
Retrieve Leads GET https://api.tomba.io/v1 /leads X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the leads of your workspace, or your own leads when you aren't in a workspace, with each lead's list and custom attribute values. list returns only the leads in one list. meta.total_pages is rounded down, so it doesn't count a last, partial page. Use meta.total to know when you've read every lead. With no matching leads, data.leads is an empty array and meta is absent. Also accepts an OAuth 2.0 access token with the leads scope. Retrieve Leads
GET /leads - Read
Retrieve a Single Lead
Retrieve a Single Lead GET https://api.tomba.io/v1 /leads/{leadId} X-Tomba-Key (header) + X-Tomba-Secret (header) Returns one lead of your workspace, as the only item of data.leads . A lead that doesn't exist, or that you can't see, returns 200 with an empty data.leads array, not 404 . Also accepts an OAuth 2.0 access token with the leads scope. Retrieve a Single Lead
GET /leads/{leadId} - Read
Check whether an email is a lead
Check whether an email is a lead GET https://api.tomba.io/v1 /leads/{email}/exist X-Tomba-Key (header) + X-Tomba-Secret (header) Returns the ID of your lead with this email address, or null when you have none. The address is trimmed and lowercased before the lookup. Only leads you saved count, not the leads of other members of your workspace. An address that isn't a valid email returns 200 with null , not 422 . Also accepts an OAuth 2.0 access token with the leads scope. Check whether an email is a lead
GET /leads/{email}/exist - Read
Phone Finder
Phone Finder GET https://api.tomba.io/v1 /phone-finder X-Tomba-Key (header) + X-Tomba-Secret (header) Finds phone numbers for a person or a company from an email address, a domain, or a LinkedIn profile URL. Send at least one of email , domain , and linkedin ; you can combine them, and the numbers found for each are merged without duplicates. The same endpoint is also available as GET /phone and GET /phone/{email} . data is one number, preferring a valid one, or an array of every number found with full=true . When nothing is found, the response is still 200 : data is an empty array and the response repeats the identifiers you sent. The cost d
GET /phone-finder - Read
Phone validator
Phone validator GET https://api.tomba.io/v1 /phone-validator X-Tomba-Key (header) + X-Tomba-Secret (header) Checks whether a phone number is valid in its country's numbering plan and returns its formats, line type, carrier, region, and time zones. For a number that isn't valid, the response is still 200 , with an empty data array and your input in phone . A number whose country can't be determined fails with 422 ; send it in international format or add country_code . See Credits and usage for when a request is charged. Phone validator
GET /phone-validator - Read
Search Companies
Search Companies POST https://api.tomba.io/v1 /reveal/search X-Tomba-Key (header) + X-Tomba-Secret (header) Searches Tomba's company database with structured filters or a natural-language query, and returns 50 companies per page. When you send query , filters are generated from it with an AI model and any filters you send are ignored. The generated filters are returned in meta.filters ; send them as filters to get the next pages without generating them again. Per-request webhooks aren't supported. This endpoint has a fixed rate limit instead of your plan's limits; see Rate limits . See Credits and usage for when a request is charged. Search C
POST /reveal/search - Read
List scrape campaigns
List scrape campaigns GET https://api.tomba.io/v1 /sla/{source}/{type} X-Tomba-Key (header) + X-Tomba-Secret (header) Lists the campaigns of one source and type, newest first, including those created by other members of your workspace. Deleted campaigns aren't listed. Each item includes its records , so a page can be large. Also accepts an OAuth 2.0 access token. List scrape campaigns
GET /sla/{source}/{type} - Read
Get a scrape campaign
Get a scrape campaign GET https://api.tomba.io/v1 /sla/{source}/{type}/{id} X-Tomba-Key (header) + X-Tomba-Secret (header) Returns one campaign of your workspace, with its records, status, and results summary. Also accepts an OAuth 2.0 access token. Get a scrape campaign
GET /sla/{source}/{type}/{id} - Read
Get scrape campaign progress
Get scrape campaign progress GET https://api.tomba.io/v1 /sla/{source}/{type}/{id}/progress X-Tomba-Key (header) + X-Tomba-Secret (header) Returns a campaign's status and progress. Poll it until status is completed or failed . Unlike the other routes, the response isn't wrapped in data . Also accepts an OAuth 2.0 access token. Get scrape campaign progress
GET /sla/{source}/{type}/{id}/progress - Read
Download scrape campaign results
Download scrape campaign results GET https://api.tomba.io/v1 /sla/{source}/{type}/{id}/download X-Tomba-Key (header) + X-Tomba-Secret (header) Downloads a result file of a completed campaign as CSV. type selects it: full (the default) has every email found, valid only those whose verification result is valid, and not_found the records with no email. A campaign without a file of that kind returns 404 . The first download charges the campaign's search_cost and verify_cost ; later downloads are free. If your balance, or your individual limit in a workspace, is lower than the cost at the first download, the response is 429 and nothing is charged.
GET /sla/{source}/{type}/{id}/download - Read
Email Verifier
Email Verifier GET https://api.tomba.io/v1 /email-verifier X-Tomba-Key (header) + X-Tomba-Secret (header) Checks whether an email address can receive mail. data.email.status and data.email.result give the outcome; the other fields report the individual checks. You can also send the address in the path, as GET /email-verifier/{email} . Email Verifier
GET /email-verifier - Write
Create a bulk job
Create a bulk job POST https://api.tomba.io/v1 /bulk/{type} X-Tomba-Key (header) + X-Tomba-Secret (header) Create a job from a list of values, data rows, or a CSV file (multipart). With data or file , each column is found from the header row unless you set its zero-based *_field_index . The options a type uses are listed in Bulk types ; unknown parameters are ignored. The job is pending until you launch it. With launch set to true , it starts right away; if it can't, it stays pending and data.message says why. A domain export ( export ) takes one domain , always starts, and needs a paid plan. Nothing is charged until the first download; see B
POST /bulk/{type} - Write
Launch a bulk job
Launch a bulk job PUT https://api.tomba.io/v1 /bulk/{type}/{id} X-Tomba-Key (header) + X-Tomba-Secret (header) Start a pending job; any other status, or an expired job, returns 409 . The launch is refused with 429 while 2 jobs of the type are running, or when a kind of credit the job needs is used up. Nothing is charged at launch; see Billing . Follow the job with GET /bulk/{type}/{id}/progress or a webhook . Launch a bulk job
PUT /bulk/{type}/{id} - Write
Retry a bulk job
Retry a bulk job POST https://api.tomba.io/v1 /bulk/{type}/{id}/retry X-Tomba-Key (header) + X-Tomba-Secret (header) Run a failed or cancelled job again from its input, with the same options. Its results and metrics are reset, retry_count goes up by one, and the job is launched. It returns 409 when the job has another status, has expired, or its input is no longer stored, and 429 like PUT /bulk/{type}/{id} . Retry a bulk job
POST /bulk/{type}/{id}/retry - Write
Rename a bulk job
Rename a bulk job PUT https://api.tomba.io/v1 /bulk/{type}/{id}/rename X-Tomba-Key (header) + X-Tomba-Secret (header) Rename a job. Rename a bulk job
PUT /bulk/{type}/{id}/rename - Write
Restore an archived bulk job
Restore an archived bulk job PUT https://api.tomba.io/v1 /bulk/{type}/{id}/restore X-Tomba-Key (header) + X-Tomba-Secret (header) Move an archived job back to the default list. A job that isn't archived returns 409 . Restore an archived bulk job
PUT /bulk/{type}/{id}/restore - Write
Flag Incorrect Data
Flag Incorrect Data POST https://api.tomba.io/v1 /flag X-Tomba-Key (header) + X-Tomba-Secret (header) Reports incorrect data: an email address that bounced or is wrong, or a wrong organization, phone number, author URL, or website. reason must be one of the reasons listed for the flag_type . Tomba reviews each report by hand. A new report has the status pending ; follow it with GET /flag . When Tomba confirms an email report with the reason hard_bounce , it returns one search credit to the usage window that's current at that moment, and the report's credits_refunded becomes 1 . Verification credits aren't returned, and other types and reasons
POST /flag - Write
Create an API Key
Create an API Key POST https://api.tomba.io/v1 /keys X-Tomba-Key (header) + X-Tomba-Secret (header) Creates an API key for your account and returns its value in data.message . The request body is optional: Without name , the key is named Default key , or Default key 2 , Default key 3 , and so on when that name is taken. Without expires_in_days , the key expires in 365 days, the maximum. You can hold as many unexpired keys as pricing.available_keys in GET /me , and at least 25 while you have unused credit-pack credits. Expired keys don't count. Past the limit, the request fails with 422 rate_limit . Tomba emails you when a key is created. Limi
POST /keys - Write
Rename an API Key
Rename an API Key PATCH https://api.tomba.io/v1 /keys/{keyId} X-Tomba-Key (header) + X-Tomba-Secret (header) Changes a key's name. The name is the only field you can edit. Expiry can't be changed: to extend a key, rotate it with PUT , which issues a new value with a new 365-day term. Any member of the key owner's workspace can rename the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the account scope. Rename an API Key
PATCH /keys/{keyId} - Write
Create a Lead Attribute
Create a Lead Attribute POST https://api.tomba.io/v1 /attributes X-Tomba-Key (header) + X-Tomba-Secret (header) Creates a custom lead attribute. Its identifier , the key for its values in a lead's attributes , is the name as a lowercase slug: Deal size becomes deal-size . The request fails with 422 when you already have an attribute with the same identifier, or already have 29 attributes, the limit on every plan. Also accepts an OAuth 2.0 access token with the leads scope. Create a Lead Attribute
POST /attributes - Write
Update a Lead Attribute
Update a Lead Attribute PUT https://api.tomba.io/v1 /attributes/{attributeId} X-Tomba-Key (header) + X-Tomba-Secret (header) Renames an attribute and sets its type. Send both fields. The identifier is rebuilt from the new name. Values already set on leads stay attached and appear under the new identifier. A name whose identifier matches the attribute's current one fails with 422 , so you can't change only the type. Only attributes you created are changed. For a teammate's attribute, the request returns 200 without changing anything. Also accepts an OAuth 2.0 access token with the leads scope. Update a Lead Attribute
PUT /attributes/{attributeId} - Write
Create Leads List
Create Leads List POST https://api.tomba.io/v1 /leads_lists X-Tomba-Key (header) + X-Tomba-Secret (header) Creates a lead list. The name must be unique among your lists. You can create as many lists as pricing.available_list in GET /me . Past that, the request fails with 422 rate_limit ; the error message mentions custom fields, but the limit is on lists. Also accepts an OAuth 2.0 access token with the leads scope. Create Leads List
POST /leads_lists - Write
Update Leads List
Update Leads List PUT https://api.tomba.io/v1 /leads_lists/{listId} X-Tomba-Key (header) + X-Tomba-Secret (header) Renames a list of your workspace, or marks or unmarks it as a favorite. favorite is always written: leaving it out sets it to false . A name already used by a list in your workspace fails with 422 , and that includes this list's own current name. Leave name out to change only favorite . Also accepts an OAuth 2.0 access token with the leads scope. Update Leads List
PUT /leads_lists/{listId} - Write
Create a Lead
Create a Lead POST https://api.tomba.io/v1 /leads X-Tomba-Key (header) + X-Tomba-Secret (header) Saves a lead to your account. Every field is optional, email included. Tomba doesn't check for duplicates: saving the same email address twice creates two leads. list_id must be a JSON number. Sent as a string, the lead is still created, but without the list and without every field that follows list_id in the request body. A list_id that isn't one of your own lists is dropped. attributes sets custom attribute values, keyed by the attribute's identifier from GET /attributes . Send the values as strings. Keys that don't match one of your attributes
POST /leads - Write
Update a lead
Update a lead PUT https://api.tomba.io/v1 /leads/{leadId} X-Tomba-Key (header) + X-Tomba-Secret (header) Updates a lead of your workspace. Send only the fields to change; the others keep their values. list_id moves the lead to that list. A list outside your workspace is ignored. attributes adds or replaces custom attribute values, keyed by the attribute's identifier . Keys that don't match an attribute of your workspace are ignored. Some limits differ from POST /leads : first_name and last_name need at least 2 characters, position takes up to 25, and twitter and linkedin up to 99. Also accepts an OAuth 2.0 access token with the leads scope. U
PUT /leads/{leadId} - Write
Create a scrape campaign
Create a scrape campaign POST https://api.tomba.io/v1 /sla/{source}/{type} X-Tomba-Key (header) + X-Tomba-Secret (header) Saves records you collected on LinkedIn, Sales Navigator, or Apollo as a campaign and starts processing it. The Tomba browser extension sends its exports here; the campaign also appears in the dashboard at https://app.tomba.io/sla/{source}/{type}/{id} . A campaign differs from a bulk job : a bulk job takes rows in Tomba's own input format, with options for each bulk type, and you launch it; a campaign takes the records as the source page gives them, keeps them, and starts at once. In both cases Tomba then looks for the ema
POST /sla/{source}/{type} - Write
Update a scrape campaign
Update a scrape campaign PUT https://api.tomba.io/v1 /sla/{source}/{type}/{id} X-Tomba-Key (header) + X-Tomba-Secret (header) Renames a campaign or sets its status. Send only the fields to change. status is stored as sent, without checking the value or the campaign's current status. Also accepts an OAuth 2.0 access token. Update a scrape campaign
PUT /sla/{source}/{type}/{id} - Write
Launch a scrape campaign
Launch a scrape campaign POST https://api.tomba.io/v1 /sla/{source}/{type}/{id}/launch X-Tomba-Key (header) + X-Tomba-Secret (header) Sets a campaign's status to running . It doesn't start or restart processing: processing starts when the campaign is created, and you don't need to call this route. Accounts on a lifetime-deal plan without premium access get 403 . Also accepts an OAuth 2.0 access token. Launch a scrape campaign
POST /sla/{source}/{type}/{id}/launch - Destructive
Cancel a bulk job
Cancel a bulk job POST https://api.tomba.io/v1 /bulk/{type}/{id}/cancel X-Tomba-Key (header) + X-Tomba-Secret (header) Cancel a pending job: its status becomes cancelled , and you can retry it later. Only a pending job can be cancelled; any other status returns 409 . Cancel a bulk job
POST /bulk/{type}/{id}/cancel - Destructive
Archive a bulk job
Archive a bulk job DELETE https://api.tomba.io/v1 /bulk/{type}/{id}/archive X-Tomba-Key (header) + X-Tomba-Secret (header) Archive a completed , failed , or cancelled job: it leaves the default list and appears with archived=true . Restore it with PUT /bulk/{type}/{id}/restore . Other statuses, and an archived job, return 409 . Archive a bulk job
DELETE /bulk/{type}/{id}/archive - Destructive
Delete a bulk job
Delete a bulk job DELETE https://api.tomba.io/v1 /bulk/{type}/{id}/delete X-Tomba-Key (header) + X-Tomba-Secret (header) Delete a job. It no longer appears in lists and its routes return 404 . Delete a bulk job
DELETE /bulk/{type}/{id}/delete - Destructive
Rotate the bulk webhook secret
Rotate the bulk webhook secret POST https://api.tomba.io/v1 /bulk/webhook-secret/rotate X-Tomba-Key (header) + X-Tomba-Secret (header) Replace the key your bulk job events are signed with. The old key stops working at once, including for events of jobs that are already running. Rotate the bulk webhook secret
POST /bulk/webhook-secret/rotate - Destructive
Reset an API Key
Reset an API Key PUT https://api.tomba.io/v1 /keys/{keyId} X-Tomba-Key (header) + X-Tomba-Secret (header) Rotates a key: issues a new value and a new 365-day expiry, and the old value stops working immediately. The key keeps its ID, name, and creator. Rotating also revives an expired key. The response doesn't include the new value; read it with GET /keys/{keyId} . Any member of the key owner's workspace can rotate the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the account scope. Reset an API Key
PUT /keys/{keyId} - Destructive
Delete an API Key
Delete an API Key DELETE https://api.tomba.io/v1 /keys/{keyId} X-Tomba-Key (header) + X-Tomba-Secret (header) Deletes a key. Requests made with it fail from then on. Any member of the key owner's workspace can delete the key. Limited to 100 requests per hour for each key ID. Also accepts an OAuth 2.0 access token with the account scope. Delete an API Key
DELETE /keys/{keyId} - Destructive
Delete a Lead Attribute
Delete a Lead Attribute DELETE https://api.tomba.io/v1 /attributes/{attributeId} X-Tomba-Key (header) + X-Tomba-Secret (header) Deletes an attribute of your workspace. Its values no longer appear on leads. Also accepts an OAuth 2.0 access token with the leads scope. Delete a Lead Attribute
DELETE /attributes/{attributeId} - Destructive
Delete Leads List
Delete Leads List DELETE https://api.tomba.io/v1 /leads_lists/{listId} X-Tomba-Key (header) + X-Tomba-Secret (header) Deletes a list of your workspace. The leads in it aren't deleted. Also accepts an OAuth 2.0 access token with the leads scope. Delete Leads List
DELETE /leads_lists/{listId} - Destructive
Delete a lead
Delete a lead DELETE https://api.tomba.io/v1 /leads/{leadId} X-Tomba-Key (header) + X-Tomba-Secret (header) Deletes a lead of your workspace, with its custom attribute values. Also accepts an OAuth 2.0 access token with the leads scope. Delete a lead
DELETE /leads/{leadId} - Destructive
Delete a scrape campaign
Delete a scrape campaign DELETE https://api.tomba.io/v1 /sla/{source}/{type}/{id} X-Tomba-Key (header) + X-Tomba-Secret (header) Deletes a campaign. It no longer appears in lists and every route returns 404 for it. Also accepts an OAuth 2.0 access token. Delete a scrape campaign
DELETE /sla/{source}/{type}/{id}
No operations match.
See How connections work for access and permissions, or browse all integrations.
Reference date: October 29, 2026. Tomba API docs.