Clearbit Company API Replacement

This guide provides step-by-step instructions for migrating from Clearbit's Company API to Tomba's /companies/find endpoint.

API Comparison

Endpoint Migration

Clearbit Company API

Code
 
GET https://company.clearbit.com/v2/companies/find?domain=tomba.io
Authorization: Bearer sk_clearbit_xxx

Tomba Company API

Code
 
GET https://api.tomba.io/v1/companies/find?domain=tomba.io
X-Tomba-Key: your-api-key
X-Tomba-Secret: your-secret-key

Response Format Comparison

Clearbit Response

Code
 
{
    "id": "027b0d40-016c-40ea-8925-a076fa640992",
    "name": "Tomba",
    "legalName": "Tomba Technology Web Service LLC",
    "domain": "tomba.io",
    "domainAliases": [],
    "url": "https://tomba.io",
    "site": {
        "title": "Tomba - Email Finder",
        "h1": "Find Anyone's Email Address",
        "metaDescription": "Tomba helps you find email addresses",
        "phoneNumbers": ["+1-234-567-8900"]
    },
    "tags": ["Technology", "B2B", "SaaS"],
    "description": "Email finding and verification platform",
    "foundedYear": 2018,
    "location": "123 Tech Street, San Francisco, CA 94105, USA",
    "timeZone": "America/Los_Angeles",
    "utcOffset": -8,
    "geo": {
        "streetNumber": "123",
        "streetName": "Tech Street",
        "subPremise": null,
        "city": "San Francisco",
        "postalCode": "94105",
        "state": "California",
        "stateCode": "CA",
        "country": "United States",
        "countryCode": "US",
        "lat": 37.7749,
        "lng": -122.4194
    },
    "logo": "https://logo.clearbit.com/tomba.io",
    "facebook": {
        "handle": "tombaio"
    },
    "linkedin": {
        "handle": "company/tomba"
    },
    "twitter": {
        "handle": "tomba_io",
        "id": "123456789",
        "followers": 5000
    },
    "crunchbase": {
        "handle": "organization/tomba"
    },
    "emailProvider": false,
    "type": "private",
    "ticker": null,
    "phone": "+1-234-567-8900",
    "metrics": {
        "alexaUsRank": 50000,
        "alexaGlobalRank": 150000,
        "googleRank": 5,
        "employees": 50,
        "employeesRange": "11-50",
        "marketCap": null,
        "raised": 2000000,
        "annualRevenue": null,
        "estimatedAnnualRevenue": "$5M-$10M"
    },
    "category": {
        "sector": "Information Technology",
        "industryGroup": "Software",
        "industry": "Application Software",
        "subIndustry": "Business Intelligence Software",
        "gicsCode": "45103010"
    },
    "tech": ["google_analytics", "stripe"],
    "parent": {
        "domain": null
    }
}

Tomba Response

Code
 
{
    "data": {
        "organization": "Tomba",
        "email_count": 15,
        "phone_number": "+1-234-567-8900",
        "website": "https://tomba.io",
        "country": "US",
        "state": "California",
        "city": "San Francisco",
        "postal_code": "94105",
        "street": "123 Tech Street",
        "revenue": "5000000-10000000",
        "employees": "11-50",
        "founded": 2018,
        "industry": "Computer Software",
        "description": "Tomba helps you find and verify professional email addresses",
        "logo": "https://d12h6n0d1mbsct.cloudfront.net/logos/tomba-io.jpg",
        "twitter": "tomba_io",
        "linkedin": "tomba",
        "facebook": "tombaio",
        "technologies": [
            {
                "name": "Google Analytics",
                "category": "Analytics",
                "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/google-analytics.png"
            },
            {
                "name": "Stripe",
                "category": "Payment",
                "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/stripe.png"
            }
        ],
        "similar_domains": ["hunter.io", "snov.io", "voilanorbert.com"]
    }
}

Field Mapping

Code Examples

Node.js / JavaScript

Before (Clearbit):

Code
 
const clearbit = require("clearbit")("sk_clearbit_xxx");

async function getCompany(domain) {
    try {
        const company = await clearbit.Company.find({ domain });
        return {
            name: company.name,
            employees: company.metrics?.employees,
            industry: company.category?.industry,
            location: `${company.geo?.city}, ${company.geo?.country}`,
        };
    } catch (error) {
        console.error("Clearbit error:", error);
        throw error;
    }
}

After (Tomba):

Code
 
const axios = require("axios");

async function getCompany(domain) {
    try {
        const response = await axios.get(
            "https://api.tomba.io/v1/companies/find",
            {
                params: { domain },
                headers: {
                    "X-Tomba-Key": process.env.TOMBA_API_KEY,
                    "X-Tomba-Secret": process.env.TOMBA_API_SECRET,
                },
            },
        );

        const company = response.data.data;
        return {
            name: company.organization,
            employees: company.employees,
            industry: company.industry,
            location: `${company.city}, ${company.country}`,
            // Bonus fields not in Clearbit
            emailCount: company.email_count,
            technologies: company.technologies?.map((t) => t.name),
            competitors: company.similar_domains,
        };
    } catch (error) {
        console.error("Tomba error:", error);
        throw error;
    }
}

// Usage
getCompany("stripe.com").then(console.log);

Python

Before (Clearbit):

Code
 
import clearbit

clearbit.key = 'sk_clearbit_xxx'

def get_company(domain):
    try:
        company = clearbit.Company.find(domain=domain)
        return {
            'name': company['name'],
            'employees': company.get('metrics', {}).get('employees'),
            'industry': company.get('category', {}).get('industry'),
            'location': f"{company.get('geo', {}).get('city')}, {company.get('geo', {}).get('country')}"
        }
    except clearbit.errors.NotFoundError:
        return None

After (Tomba):

Code
 
import requests
import os

def get_company(domain):
    try:
        response = requests.get(
            'https://api.tomba.io/v1/companies/find',
            params={'domain': domain},
            headers={
                'X-Tomba-Key': os.getenv('TOMBA_API_KEY'),
                'X-Tomba-Secret': os.getenv('TOMBA_API_SECRET')
            }
        )
        response.raise_for_status()

        company = response.json()['data']
        return {
            'name': company['organization'],
            'employees': company.get('employees'),
            'industry': company.get('industry'),
            'location': f"{company.get('city')}, {company.get('country')}",
            # Bonus fields
            'email_count': company.get('email_count'),
            'technologies': [t['name'] for t in company.get('technologies', [])],
            'competitors': company.get('similar_domains', [])
        }
    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 404:
            return None
        raise

# Usage
company = get_company('stripe.com')
print(company)

PHP

Before (Clearbit):

Code
 
<?php
require 'vendor/autoload.php';

use Clearbit\Clearbit;

Clearbit::setApiKey('sk_clearbit_xxx');

function getCompany($domain) {
    try {
        $company = Clearbit::company()->find(['domain' => $domain]);

        return [
            'name' => $company->name,
            'employees' => $company->metrics->employees ?? null,
            'industry' => $company->category->industry ?? null,
            'location' => "{$company->geo->city}, {$company->geo->country}"
        ];
    } catch (\Clearbit\Errors\NotFoundError $e) {
        return null;
    }
}

After (Tomba):

Code
 
<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;

function getCompany($domain) {
    $client = new Client();

    try {
        $response = $client->get('https://api.tomba.io/v1/companies/find', [
            'query' => ['domain' => $domain],
            'headers' => [
                'X-Tomba-Key' => getenv('TOMBA_API_KEY'),
                'X-Tomba-Secret' => getenv('TOMBA_API_SECRET')
            ]
        ]);

        $company = json_decode($response->getBody())->data;

        return [
            'name' => $company->organization,
            'employees' => $company->employees ?? null,
            'industry' => $company->industry ?? null,
            'location' => "{$company->city}, {$company->country}",
            // Bonus fields
            'email_count' => $company->email_count ?? 0,
            'technologies' => array_map(fn($t) => $t->name, $company->technologies ?? []),
            'competitors' => $company->similar_domains ?? []
        ];
    } catch (\GuzzleHttp\Exception\ClientException $e) {
        if ($e->getResponse()->getStatusCode() === 404) {
            return null;
        }
        throw $e;
    }
}

// Usage
$company = getCompany('stripe.com');
print_r($company);

Ruby

Before (Clearbit):

Code
 
require 'clearbit'

Clearbit.key = 'sk_clearbit_xxx'

def get_company(domain)
  company = Clearbit::Enrichment::Company.find(domain: domain)

  {
    name: company.name,
    employees: company.metrics&.employees,
    industry: company.category&.industry,
    location: "#{company.geo&.city}, #{company.geo&.country}"
  }
rescue Clearbit::NotFoundError
  nil
end

After (Tomba):

Code
 
require 'httparty'

def get_company(domain)
  response = HTTParty.get(
    'https://api.tomba.io/v1/companies/find',
    query: { domain: domain },
    headers: {
      'X-Tomba-Key' => ENV['TOMBA_API_KEY'],
      'X-Tomba-Secret' => ENV['TOMBA_API_SECRET']
    }
  )

  return nil if response.code == 404
  raise "API Error: #{response.code}" unless response.success?

  company = response.parsed_response['data']

  {
    name: company['organization'],
    employees: company['employees'],
    industry: company['industry'],
    location: "#{company['city']}, #{company['country']}",
    # Bonus fields
    email_count: company['email_count'],
    technologies: company['technologies']&.map { |t| t['name'] },
    competitors: company['similar_domains']
  }
end

# Usage
company = get_company('stripe.com')
puts company

Enhanced Features

Technology Stack Detection

Tomba provides detailed technology information not available in Clearbit:

Code
 
const response = await axios.get("https://api.tomba.io/v1/companies/find", {
    params: { domain: "shopify.com" },
    headers: {
        "X-Tomba-Key": process.env.TOMBA_API_KEY,
        "X-Tomba-Secret": process.env.TOMBA_API_SECRET,
    },
});

console.log("Technologies used:");
response.data.data.technologies.forEach((tech) => {
    console.log(`- ${tech.name} (${tech.category})`);
});

// Output:
// - Google Analytics (Analytics)
// - Stripe (Payment Processing)
// - Cloudflare (CDN)
// - Shopify (E-commerce)
// - Mailchimp (Email Marketing)

Similar Companies / Competitors

Find competitors automatically:

Code
 
const company = response.data.data;
console.log(`Companies similar to ${company.organization}:`);
console.log(company.similar_domains);

// Output:
// ['bigcommerce.com', 'woocommerce.com', 'magento.com']

Email Count

Know how many contacts are available:

Code
 
const company = response.data.data;
console.log(
    `${company.email_count} contacts available at ${company.organization}`,
);

// Output: "147 contacts available at Shopify"

Error Handling

Clearbit Errors

Code
 
try {
    const company = await clearbit.Company.find({ domain });
} catch (error) {
    if (error.type === "not_found") {
        // Company not found
    } else if (error.type === "rate_limit") {
        // Rate limited
    } else if (error.type === "invalid_request") {
        // Bad request
    }
}

Tomba Errors

Code
 
try {
    const response = await axios.get("https://api.tomba.io/v1/companies/find", {
        params: { domain },
        headers: {
            "X-Tomba-Key": process.env.TOMBA_API_KEY,
            "X-Tomba-Secret": process.env.TOMBA_API_SECRET,
        },
    });
} catch (error) {
    if (error.response?.status === 404) {
        // Company not found
        console.log("Company not found in database");
    } else if (error.response?.status === 429) {
        // Rate limited
        console.log("Rate limit exceeded");
    } else if (error.response?.status === 400) {
        // Bad request
        console.log("Invalid domain format");
    } else if (error.response?.status === 401) {
        // Authentication failed
        console.log("Invalid API credentials");
    }
}

Testing

Sample Test Cases

Code
 
const assert = require("assert");

describe("Company API Migration", () => {
    it("should return company data for valid domain", async () => {
        const company = await getCompany("stripe.com");

        assert(company.name);
        assert(company.location);
        assert(company.industry);
        assert.ok(company.emailCount > 0); // New field
    });

    it("should return null for non-existent domain", async () => {
        const company = await getCompany("thisdoesnotexist12345.com");
        assert.strictEqual(company, null);
    });

    it("should include technology data", async () => {
        const company = await getCompany("shopify.com");
        assert(Array.isArray(company.technologies));
        assert(company.technologies.length > 0);
    });

    it("should include similar companies", async () => {
        const company = await getCompany("salesforce.com");
        assert(Array.isArray(company.competitors));
    });
});

Migration Checklist

• Update authentication to use API Key + Secret headers
• Change base URL to api.tomba.io/v1
• Update field mappings in your code
• Add handling for new fields (technologies, similar_domains, email_count)
• Update error handling for Tomba response codes
• Test with sample domains
• Update type definitions/interfaces
• Test edge cases (invalid domains, rate limits)
• Deploy to staging environment
• Monitor API responses
• Deploy to production

Next Steps

• Person API Migration - Enrich person data
• Combined API Migration - Get person + company data
• Full API Documentation

Need help with migration?

Contact our support team at support@tomba.io for personalized migration assistance.