openapi: 3.0.1
info:
  title: Tomba
  description: |-
    The Tomba API provides programmatic access to email discovery, verification, enrichment, and company intelligence workflows. Find professional emails, validate deliverability, retrieve sources, and automate prospecting at scale using simple REST endpoints.

    ## Getting Started

    To begin, send authenticated requests using your API credentials in the request headers. Start with domain search or email finder, then verify addresses and enrich contacts as needed for your workflow.

    ```sh
    curl -X GET 'https://api.tomba.io/v1/email-finder?domain=tomba.io&first_name=emily&last_name=harris' \
      -H "X-Tomba-Key: your_api_key" \
      -H "X-Tomba-Secret: your_api_secret"
    ```

    ## Rate Limits

    Rate limits are enforced **per endpoint** and **per plan** across three dimensions: per-second (rps), per-minute (rpm), and per-day. Your daily limit equals your monthly credits divided by 5.

    | Plan        | Per Second | Per Minute | Per Day           |
    |-------------|-----------|------------|-------------------|
    | Free        | 1         | 2          | 5                 |
    | Basic       | 3         | 50         | 500               |
    | Growth      | 5         | 80         | 1,000             |
    | Pro         | 8         | 150        | 4,000             |
    | PAYG 20k    | 10        | 200        | 4,000             |
    | **50k+**    | Unlimited | Unlimited  | Unlimited         |

    All plans with 50,000+ credits (Pro Plus, Enterprise, Scale, PAYG 50k+) have **no rate limits**. Full details at [Rate Limits](https://docs.tomba.io/rate-limits). [Upgrade your plan](https://app.tomba.io/upgrade) for higher throughput.

    ### Rate Limit Headers

    Each API response includes these headers:

    - `RateLimit-Policy`: Rate limit policies with quota and window (e.g. `"rps";q=8;w=1, "daily";q=4000;w=86400`)
    - `RateLimit`: Remaining quota and time until reset (e.g. `"rps";r=7;t=1, "daily";r=3842;t=64802`)
    - `x-second-rate-limit`: Total per-second request limit
    - `x-minute-rate-limit`: Total per-minute request limit
    - `x-daily-rate-limit`: Total daily request limit
    - `x-minute-request-left`: Remaining requests for the minute
    - `x-daily-request-left`: Remaining requests for the day
    - `x-minute-reset-seconds`: Seconds until minute limit resets
    - `x-daily-reset-seconds`: Seconds until daily limit resets
    - `Retry-After`: Seconds to wait (on 429 responses only)

    When any limit is exceeded, the API returns `429 Too Many Requests` with a `Retry-After` header.

    ### Check Your Usage

    Use `GET /v1/rate-limits` to see your current usage per endpoint.

    ## Authentication

    All endpoints require both authentication headers: `X-Tomba-Key` and `X-Tomba-Secret`. Requests without valid credentials return unauthorized errors.

    ## Versioning

    The current stable API base URL is `https://api.tomba.io/v1`. Backward-compatible improvements may be released without changing the major version path.

    ## Performance

    Recommended client timeout: **180 seconds**. Searches run in real time against live infrastructure — response times vary with the target company's SMTP server speed, website responsiveness, and the depth of catch-all detection. Set generous timeouts and use asynchronous calls or bulk endpoints for high-volume workflows.

    ## Support

    For questions, troubleshooting, or integration help, contact support at [info@tomba.io](mailto:info@tomba.io) or visit the documentation at https://docs.tomba.io.

    ## MCP Server

    Tomba also provides a [Model Context Protocol (MCP) server](/api#mcp-server) for AI assistants. Connect Claude, ChatGPT, Cursor, VS Code, and other AI tools to Tomba's data via the standardized MCP protocol at `https://mcp.tomba.io/mcp`.

    The MCP server supports three authentication methods:

    - **OAuth 2.0** (Recommended for Claude Desktop) — auto-discovers endpoints and opens a browser for authorization
    - **Bearer Token** — Base64-encode your credentials as `apiKey:secretKey`:
      ```
      Authorization: Bearer base64(apiKey:secretKey)
      ```
    - **API Key Headers** — pass credentials directly:
      ```
      X-Tomba-Key: your_api_key
      X-Tomba-Secret: your_api_secret
      ```

    Get your API credentials at [app.tomba.io/api](https://app.tomba.io/api).
  termsOfService: https://tomba.io/privacy-policy
  contact:
    name: Tomba technology web service LLC
    url: https://tomba.io
    email: info@tomba.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.0.0
servers:
  - url: https://api.tomba.io/v1
    description: Production server
paths:
  /me:
    $ref: 'paths/me.yaml'
  /reveal/search:
    $ref: 'paths/reveal_search.yaml'
  /domain-search:
    $ref: 'paths/domainsearch.yaml'
  /email-finder:
    $ref: 'paths/emailfinder.yaml'
  /email-verifier:
    $ref: 'paths/emailverifier.yaml'
  /phone-finder:
    $ref: 'paths/phonefinder.yaml'
  /phone-validator:
    $ref: 'paths/phonevalidator.yaml'
  /email-sources:
    $ref: 'paths/emailsources.yaml'
  /domain-status:
    $ref: 'paths/domainstatus.yaml'
  /email-count:
    $ref: 'paths/emailcount.yaml'
  /domain-suggestions:
    $ref: 'paths/domainsuggestions.yaml'
  /email-format:
    $ref: 'paths/emailformat.yaml'
  /location:
    $ref: 'paths/location.yaml'
  /similar:
    $ref: 'paths/similar.yaml'
  /technology:
    $ref: 'paths/technology.yaml'
  /author-finder:
    $ref: 'paths/authorfinder.yaml'
  /bulk/search:
    $ref: 'paths/bulk_search.yaml'
  /bulk/search/{id}:
    $ref: 'paths/bulk_search_{id}.yaml'
  /bulk/search/{id}/delete:
    $ref: 'paths/bulk_search_{id}_delete.yaml'
  /bulk/search/{id}/archive:
    $ref: 'paths/bulk_search_{id}_archive.yaml'
  /bulk/search/{id}/progress:
    $ref: 'paths/bulk_search_{id}_progress.yaml'
  /bulk/search/{id}/download:
    $ref: 'paths/bulk_search_{id}_download.yaml'
  /bulk/search/{id}/rename:
    $ref: 'paths/bulk_search_{id}_rename.yaml'
  /bulk/similar:
    $ref: 'paths/bulk_similar.yaml'
  /bulk/similar/{id}:
    $ref: 'paths/bulk_similar_{id}.yaml'
  /bulk/similar/{id}/delete:
    $ref: 'paths/bulk_similar_{id}_delete.yaml'
  /bulk/similar/{id}/archive:
    $ref: 'paths/bulk_similar_{id}_archive.yaml'
  /bulk/similar/{id}/progress:
    $ref: 'paths/bulk_similar_{id}_progress.yaml'
  /bulk/similar/{id}/download:
    $ref: 'paths/bulk_similar_{id}_download.yaml'
  /bulk/similar/{id}/rename:
    $ref: 'paths/bulk_similar_{id}_rename.yaml'
  /bulk/company:
    $ref: 'paths/bulk_company.yaml'
  /bulk/company/{id}:
    $ref: 'paths/bulk_company_{id}.yaml'
  /bulk/company/{id}/delete:
    $ref: 'paths/bulk_company_{id}_delete.yaml'
  /bulk/company/{id}/archive:
    $ref: 'paths/bulk_company_{id}_archive.yaml'
  /bulk/company/{id}/progress:
    $ref: 'paths/bulk_company_{id}_progress.yaml'
  /bulk/company/{id}/download:
    $ref: 'paths/bulk_company_{id}_download.yaml'
  /bulk/company/{id}/rename:
    $ref: 'paths/bulk_company_{id}_rename.yaml'
  /bulk/finder:
    $ref: 'paths/bulk_finder.yaml'
  /bulk/finder/{id}:
    $ref: 'paths/bulk_finder_{id}.yaml'
  /bulk/finder/{id}/delete:
    $ref: 'paths/bulk_finder_{id}_delete.yaml'
  /bulk/finder/{id}/archive:
    $ref: 'paths/bulk_finder_{id}_archive.yaml'
  /bulk/finder/{id}/progress:
    $ref: 'paths/bulk_finder_{id}_progress.yaml'
  /bulk/finder/{id}/download:
    $ref: 'paths/bulk_finder_{id}_download.yaml'
  /bulk/finder/{id}/rename:
    $ref: 'paths/bulk_finder_{id}_rename.yaml'
  /bulk/enrich:
    $ref: 'paths/bulk_enrich.yaml'
  /bulk/enrich/{id}:
    $ref: 'paths/bulk_enrich_{id}.yaml'
  /bulk/enrich/{id}/delete:
    $ref: 'paths/bulk_enrich_{id}_delete.yaml'
  /bulk/enrich/{id}/archive:
    $ref: 'paths/bulk_enrich_{id}_archive.yaml'
  /bulk/enrich/{id}/progress:
    $ref: 'paths/bulk_enrich_{id}_progress.yaml'
  /bulk/enrich/{id}/download:
    $ref: 'paths/bulk_enrich_{id}_download.yaml'
  /bulk/enrich/{id}/rename:
    $ref: 'paths/bulk_enrich_{id}_rename.yaml'
  /bulk/linkedin:
    $ref: 'paths/bulk_linkedin.yaml'
  /bulk/linkedin/{id}:
    $ref: 'paths/bulk_linkedin_{id}.yaml'
  /bulk/linkedin/{id}/delete:
    $ref: 'paths/bulk_linkedin_{id}_delete.yaml'
  /bulk/linkedin/{id}/archive:
    $ref: 'paths/bulk_linkedin_{id}_archive.yaml'
  /bulk/linkedin/{id}/progress:
    $ref: 'paths/bulk_linkedin_{id}_progress.yaml'
  /bulk/linkedin/{id}/download:
    $ref: 'paths/bulk_linkedin_{id}_download.yaml'
  /bulk/linkedin/{id}/rename:
    $ref: 'paths/bulk_linkedin_{id}_rename.yaml'
  /bulk/author:
    $ref: 'paths/bulk_author.yaml'
  /bulk/author/{id}:
    $ref: 'paths/bulk_author_{id}.yaml'
  /bulk/author/{id}/delete:
    $ref: 'paths/bulk_author_{id}_delete.yaml'
  /bulk/author/{id}/archive:
    $ref: 'paths/bulk_author_{id}_archive.yaml'
  /bulk/author/{id}/progress:
    $ref: 'paths/bulk_author_{id}_progress.yaml'
  /bulk/author/{id}/download:
    $ref: 'paths/bulk_author_{id}_download.yaml'
  /bulk/author/{id}/rename:
    $ref: 'paths/bulk_author_{id}_rename.yaml'
  /bulk/verifier:
    $ref: 'paths/bulk_verifier.yaml'
  /bulk/verifier/{id}:
    $ref: 'paths/bulk_verifier_{id}.yaml'
  /bulk/verifier/{id}/delete:
    $ref: 'paths/bulk_verifier_{id}_delete.yaml'
  /bulk/verifier/{id}/archive:
    $ref: 'paths/bulk_verifier_{id}_archive.yaml'
  /bulk/verifier/{id}/progress:
    $ref: 'paths/bulk_verifier_{id}_progress.yaml'
  /bulk/verifier/{id}/download:
    $ref: 'paths/bulk_verifier_{id}_download.yaml'
  /bulk/verifier/{id}/rename:
    $ref: 'paths/bulk_verifier_{id}_rename.yaml'
  /bulk/phone-finder:
    $ref: 'paths/bulk_phonefinder.yaml'
  /bulk/phone-finder/{id}:
    $ref: 'paths/bulk_phonefinder_{id}.yaml'
  /bulk/phone-finder/{id}/delete:
    $ref: 'paths/bulk_phonefinder_{id}_delete.yaml'
  /bulk/phone-finder/{id}/archive:
    $ref: 'paths/bulk_phonefinder_{id}_archive.yaml'
  /bulk/phone-finder/{id}/progress:
    $ref: 'paths/bulk_phonefinder_{id}_progress.yaml'
  /bulk/phone-finder/{id}/download:
    $ref: 'paths/bulk_phonefinder_{id}_download.yaml'
  /bulk/phone-finder/{id}/rename:
    $ref: 'paths/bulk_phonefinder_{id}_rename.yaml'
  /bulk/phone-validator:
    $ref: 'paths/bulk_phonevalidator.yaml'
  /bulk/phone-validator/{id}:
    $ref: 'paths/bulk_phonevalidator_{id}.yaml'
  /bulk/phone-validator/{id}/delete:
    $ref: 'paths/bulk_phonevalidator_{id}_delete.yaml'
  /bulk/phone-validator/{id}/archive:
    $ref: 'paths/bulk_phonevalidator_{id}_archive.yaml'
  /bulk/phone-validator/{id}/progress:
    $ref: 'paths/bulk_phonevalidator_{id}_progress.yaml'
  /bulk/phone-validator/{id}/download:
    $ref: 'paths/bulk_phonevalidator_{id}_download.yaml'
  /bulk/phone-validator/{id}/rename:
    $ref: 'paths/bulk_phonevalidator_{id}_rename.yaml'
  /linkedin:
    $ref: 'paths/linkedin.yaml'
  /enrich:
    $ref: 'paths/enrich.yaml'
  /companies/find:
    $ref: 'paths/companies_find.yaml'
  /people/find:
    $ref: 'paths/people_find.yaml'
  /combined/find:
    $ref: 'paths/combined_find.yaml'
  /leads:
    $ref: 'paths/leads.yaml'
  /leads/{leadId}:
    $ref: 'paths/leads_{leadId}.yaml'
  /attributes:
    $ref: 'paths/attributes.yaml'
  /attributes/{attributeId}:
    $ref: 'paths/attributes_{attributeId}.yaml'
  /leads_lists:
    $ref: 'paths/leads_lists.yaml'
  /leads_lists/{listId}:
    $ref: 'paths/leads_lists_{listId}.yaml'
  /keys:
    $ref: 'paths/keys.yaml'
  /keys/{keyId}:
    $ref: 'paths/keys_{keyId}.yaml'
  /usage:
    $ref: 'paths/usage.yaml'
  /logs:
    $ref: 'paths/logs.yaml'
  /flag:
    $ref: 'paths/flag.yaml'
  /mcp:
    $ref: 'paths/mcp.yaml'
components:
  parameters:
    BulkIdParam:
      $ref: 'components/parameters/BulkIdParam.yaml'
    DirectionParam:
      $ref: 'components/parameters/DirectionParam.yaml'
    DownloadTypeParam:
      $ref: 'components/parameters/DownloadTypeParam.yaml'
    FilterParam:
      $ref: 'components/parameters/FilterParam.yaml'
    LimitParam:
      $ref: 'components/parameters/LimitParam.yaml'
    PageParam:
      $ref: 'components/parameters/PageParam.yaml'
  schemas:
    RevealSearchRequest:
      $ref: 'components/schemas/RevealSearchRequest.yaml'
    RevealFilters:
      $ref: 'components/schemas/RevealFilters.yaml'
    SearchFilter:
      $ref: 'components/schemas/SearchFilter.yaml'
    PremiumSearchFilter:
      $ref: 'components/schemas/PremiumSearchFilter.yaml'
    RevealSearchResponse:
      $ref: 'components/schemas/RevealSearchResponse.yaml'
    RevealMeta:
      $ref: 'components/schemas/RevealMeta.yaml'
    RevealData:
      $ref: 'components/schemas/RevealData.yaml'
    Company:
      $ref: 'components/schemas/Company.yaml'
    Account:
      $ref: 'components/schemas/Account.yaml'
    DomainSearch:
      $ref: 'components/schemas/DomainSearch.yaml'
    EmailFinder:
      $ref: 'components/schemas/EmailFinder.yaml'
    EmailSource:
      $ref: 'components/schemas/EmailSource.yaml'
    FinderVerification:
      $ref: 'components/schemas/FinderVerification.yaml'
    PhoneData:
      $ref: 'components/schemas/PhoneData.yaml'
    EmailVerifier:
      $ref: 'components/schemas/EmailVerifier.yaml'
    EnrichmentPersonAPI:
      $ref: 'components/schemas/EnrichmentPersonAPI.yaml'
    EnrichmentCompanyAPI:
      $ref: 'components/schemas/EnrichmentCompanyAPI.yaml'
    EnrichmentCombinedAPI:
      $ref: 'components/schemas/EnrichmentCombinedAPI.yaml'
    EmailCount:
      $ref: 'components/schemas/EmailCount.yaml'
    Location:
      $ref: 'components/schemas/Location.yaml'
    EmailSources:
      $ref: 'components/schemas/EmailSources.yaml'
    EmailFormat:
      $ref: 'components/schemas/EmailFormat.yaml'
    DomainSimilar:
      $ref: 'components/schemas/DomainSimilar.yaml'
    DomainTechnology:
      $ref: 'components/schemas/DomainTechnology.yaml'
    PhoneFinder:
      $ref: 'components/schemas/PhoneFinder.yaml'
    Lead:
      $ref: 'components/schemas/Lead.yaml'
    LeadAttribute:
      $ref: 'components/schemas/LeadAttribute.yaml'
    LeadsList:
      $ref: 'components/schemas/LeadsList.yaml'
    APIKey:
      $ref: 'components/schemas/APIKey.yaml'
    Usage:
      $ref: 'components/schemas/Usage.yaml'
    Log:
      $ref: 'components/schemas/Log.yaml'
    OperationSuccess:
      $ref: 'components/schemas/OperationSuccess.yaml'
    APIErrorResponse:
      $ref: 'components/schemas/APIErrorResponse.yaml'
    BulkDef:
      $ref: 'components/schemas/BulkDef.yaml'
    BulkPutRename:
      $ref: 'components/schemas/BulkPutRename.yaml'
    BulkPostSearch:
      $ref: 'components/schemas/BulkPostSearch.yaml'
    BulkPostFinder:
      $ref: 'components/schemas/BulkPostFinder.yaml'
    BulkPhoneValidator:
      $ref: 'components/schemas/BulkPhoneValidator.yaml'
    BulkItem:
      $ref: 'components/schemas/BulkItem.yaml'
    BulkProgress:
      $ref: 'components/schemas/BulkProgress.yaml'
    PaginationMeta:
      $ref: 'components/schemas/PaginationMeta.yaml'
    CreatedResourceID:
      $ref: 'components/schemas/CreatedResourceID.yaml'
    DeleteResponse:
      $ref: 'components/schemas/DeleteResponse.yaml'
    APIError:
      $ref: 'components/schemas/APIError.yaml'
    DomainSuggestionsResponse:
      $ref: 'components/schemas/DomainSuggestionsResponse.yaml'
    DomainSuggestion:
      $ref: 'components/schemas/DomainSuggestion.yaml'
    SuggestionsMeta:
      $ref: 'components/schemas/SuggestionsMeta.yaml'
    LinkedinFinder:
      $ref: 'components/schemas/LinkedinFinder.yaml'
    LinkedinFinderData:
      $ref: 'components/schemas/LinkedinFinderData.yaml'
    LinkedinFinderSource:
      $ref: 'components/schemas/LinkedinFinderSource.yaml'
    LinkedinFinderVerification:
      $ref: 'components/schemas/LinkedinFinderVerification.yaml'
    AuthorFinder:
      $ref: 'components/schemas/AuthorFinder.yaml'
    AuthorInfo:
      $ref: 'components/schemas/AuthorInfo.yaml'
    FlagCreateRequest:
      $ref: 'components/schemas/FlagCreateRequest.yaml'
    FlagItem:
      $ref: 'components/schemas/FlagItem.yaml'
    FlagResponse:
      $ref: 'components/schemas/FlagResponse.yaml'
    FlagListResponse:
      $ref: 'components/schemas/FlagListResponse.yaml'
  responses:
    BulkListResponse:
      $ref: 'components/responses/BulkListResponse.yaml'
    BulkDetailResponse:
      $ref: 'components/responses/BulkDetailResponse.yaml'
    BulkCreateResponse:
      $ref: 'components/responses/BulkCreateResponse.yaml'
    BulkProgressResponse:
      $ref: 'components/responses/BulkProgressResponse.yaml'
    SuccessResponse:
      $ref: 'components/responses/SuccessResponse.yaml'
    ValidationError:
      $ref: 'components/responses/ValidationError.yaml'
    NotFoundError:
      $ref: 'components/responses/NotFoundError.yaml'
    RateLimitError:
      $ref: 'components/responses/RateLimitError.yaml'
  securitySchemes:
    BearerAuth:
      $ref: 'components/securitySchemes/BearerAuth.yaml'
    Tomba-Api-Key:
      $ref: 'components/securitySchemes/Tomba-Api-Key.yaml'
    Tomba-Api-Secret:
      $ref: 'components/securitySchemes/Tomba-Api-Secret.yaml'
tags:
  - name: Domain Suggestions
    description: Discover similar companies and related domains
    externalDocs:
      description: Find out more about domain suggestions
      url: https://docs.tomba.io/api/domain-suggestions#get-domain-suggestions
  - name: Reveal
    description: Company search and discovery operations
  - name: Account
    description: Account details, credits, and workspace settings
  - name: Finder
    description: Find professional emails by domain, name, or source
  - name: Verifier
    description: Validate email deliverability and mailbox status
  - name: Phone
    description: Find and validate phone numbers for contacts
  - name: Bulks
    description: Create, launch, and download bulk processing jobs
  - name: Enrichment
    description: Enrich people and company data with additional signals
  - name: Leads
    description: Manage leads and prospect records
  - name: Lead Attributes
    description: Define and retrieve custom lead attributes
  - name: Lead Lists
    description: Create and organize lead lists
  - name: Keys
    description: Manage API keys and access credentials
  - name: Flag
    description: Report incorrect data and hard bounces for credit recovery
  - name: MCP Server
    description: Tomba MCP Server providing email discovery, verification, phone lookup, and company intelligence tools via the Model Context Protocol
externalDocs:
  description: Developers - Full API docs
  url: https://docs.tomba.io
security:
  - Tomba-Api-Key: []
    Tomba-Api-Secret: []