Skip to content
Changelog

Report a bug

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

    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}

See How connections work for access and permissions, or browse all integrations.

Reference date: October 29, 2026. Tomba API docs.