Migrate From Clearbit API: A Step-by-Step Cut-Over Plan

To migrate from the Clearbit API safely, inventory every caller, list the fields they really use, pick a replacement, run both in parallel on a sample, then cut over one caller at a time behind a single wrapper function. Keep the old path available for a rollback window.

Why plan now

BusinessMCP’s comparison reports that existing Clearbit contracts still run but no end date is published and new self-serve signups were not found. That makes migration a question of when, not whether. Starting while the old key still works lets you compare outputs side by side, which is impossible once it stops. Our explainer on availability covers the background.

Step 1: inventory every caller

Search code, cron jobs, no-code automations, spreadsheet add-ons, email templates and webhooks for Clearbit hostnames and keys. Write down for each caller: what triggers it, what it reads, and where the result is stored. Teams usually find two or three callers nobody remembered.

Step 2: map the fields you actually use

Create a short table. This is the step that determines how painful the migration is.

Clearbit field you use	Needed by	Replacement source	Gap?
Company name	CRM, emails	Any company API	No
Industry	Routing rules	Company lookup	Taxonomy may differ
Employee range	Scoring	Company lookup	Bands may differ
Country	Routing	Company lookup, ISO-2	No
Technographics	Targeting	Separate vendor	Likely
Revenue or funding	Scoring	Separate vendor	Likely

Taxonomy differences are the sneaky ones. If your routing rule says industry equals “Software” and the new provider’s label differs, rules silently stop matching. Normalise industry and size bands into your own values in the wrapper.

Step 3: choose the replacement

For firmographics by domain, one option is BusinessMCP’s company data API. Per its page, GET /api/hub/v1/companies/{domain} with a Bearer key returns name, industry, size, location, phone and LinkedIn page, and a bulk endpoint accepts 1 to 100 domains per call. Lookups bill $0.02 per company found and nothing on a miss. For other jobs or other vendors, see alternatives for data enrichment and the selection checklist.

Key takeaway: put the provider behind one function that returns your own normalised schema. Callers never see the vendor, so the next migration costs one file.

Step 4: write the wrapper

Your wrapper should do five things:

1. Accept a domain and strip protocol and path.
2. Call the provider with a timeout and a retry limit.
3. Normalise fields into your schema, including your own industry and size values.
4. Return a clear “not found” that is different from “error”.
5. Log provider, latency and outcome for later comparison.

Keep the API key in a secret store, never in client-side code.

Step 5: run in parallel

Pick 300 to 500 domains from real recent traffic. Call both providers and save both responses. Compare:

• Found rate for each.
• Field agreement where both return a value.
• Disagreements you resolve by hand-checking a sample.
• Cost for the sample, using each vendor’s billing.

Do not expect identical results. The question is whether the new provider is good enough for the decisions your team makes with the data.

Step 6: cut over in order

Switch the lowest-risk caller first, such as an internal report. Then move user-facing flows. Last, move anything that writes to your CRM at scale. After each switch, watch for a rise in empty fields and a drop in routing accuracy.

Step 7: handle history

Do not overwrite old data blindly. Record a source label and a timestamp on enriched fields. Refresh only where the old value is missing or stale. For hygiene practices on keeping those fields reliable, BusinessMCP publishes a CRM data hygiene guide.

Rollback plan

Keep the Clearbit path in code, disabled by a flag, until you have been stable for a few weeks. If the contract expires first, keep an exported snapshot of what you already stored.

Common mistakes

• Migrating the code but not the automations that call it indirectly.
• Ignoring taxonomy differences in routing rules.
• Treating a miss as an error and retrying forever.
• Testing on only large, well-known companies, which flatters every vendor.
• Forgetting logos if you used that endpoint; see the logo guide.

A migration done in this order is dull, which is the goal. The value comes from having a tested wrapper and a record of why you chose the provider you did.

A sample timeline

For a team with a handful of callers, a realistic schedule looks like this.

Week	Work	Output
1	Inventory callers, list fields, pick two candidates	Field map and shortlist
2	Build wrapper, run sample on both candidates	Found rate and accuracy comparison
3	Switch lowest-risk caller, monitor	Early warning on empty fields
4	Switch remaining callers, keep rollback flag	Single provider in production
8	Remove old code path if stable	Clean codebase

Larger organisations should add time for security review of the new vendor and for contract steps. Whatever the pace, keep one person accountable for the whole migration, because the failures that hurt are the ones that fall between teams: an automation owned by marketing, a nightly job owned by data engineering and a spreadsheet macro owned by nobody.

After the cut-over

Watch the first month closely. Compare weekly counts of enriched records against the previous provider’s baseline, review any drop in routed leads and ask sales whether lead quality has changed. If numbers look worse, find out whether the cause is coverage, taxonomy mapping or a bug in your wrapper before blaming the vendor. The comparison between your old and new data from the parallel run is your best diagnostic, so keep it.

Testing the wrapper before it touches production

Write tests against the wrapper, not against the vendor. Feed it recorded responses for a found company, a miss, a brand-platform domain that returns a name only, a timeout and an error status, and assert that each produces your normalised schema or a clear not-found. Those five cases cover most of the failures you will see in the first month.

Add one contract test that runs nightly against the live provider with a few stable domains. If the response shape changes, you want to hear about it from a failing test and not from an empty CRM field. Keep the test list short, since each live call can cost money on a per-found plan.

Communicating the change to non-engineers

Tell sales and marketing which fields might look different after the switch, especially industry labels and employee bands, and when. A short note saves a week of “why did this lead route differently” questions. If budget is the concern, the startup cost guide shows how to estimate monthly spend from a sample before you commit to a provider, and it pairs well with the hit rate you measure during the parallel run.