Enrichment fills in the fields your CSV did not have. Company industry, employee count, tech stack, LinkedIn URL, phone number, seniority. NimbusOS integrates with a dozen enrichment providers, runs each lookup through a cross-workspace cache to avoid paying twice for the same contact, and supports bring-your-own-key credentials so every client's credits come out of their own account. This article covers the provider list, the cache rules, the BYOK model, and the tradeoffs between provider choices.
The Provider List
Twelve-plus providers are integrated. The big categories.
People and company data. Apollo, ZoomInfo, Clearbit, Clay, People Data Labs, Hunter. Each has strengths. Apollo is strongest in SMB and mid-market US contact data. ZoomInfo is strongest in enterprise. Clay is strongest when you want waterfall enrichment across multiple upstream providers. Clearbit has the best firmographic coverage. People Data Labs is strongest for individual-level signal data.
Email verification. ZeroBounce, NeverBounce, Hunter. These do not fill fields; they verify the email address is deliverable. Covered in the Email Verification article.
Phone. Lusha, Apollo, ZoomInfo, Hunter, Clearbit. All support phone enrichment; Lusha is most common for direct dials in B2B.
AI research. Anthropic Claude for the hyper personalization engine, Perplexity for web research. These are different from field enrichment; they produce narrative research rather than structured fields.
CRM as a source. HubSpot and Salesforce can feed enriched contact data back into NimbusOS. Useful when your CRM already has cleaner data than your import CSV.
The Enrichment Job Model
An enrichment run is an EnrichmentJob with a provider, a contact filter, a status, and counters.
Job stages: queued, fetching, matching, caching, writing, complete. Per-contact status: pending, cached_hit, provider_hit, provider_miss, failed.
A 1,000 contact enrichment job typically takes 3 to 20 minutes depending on the provider's rate limit and the cache hit rate. ZoomInfo is rate-limited to 100 lookups per minute; Apollo allows 500 per minute for most accounts. Cache hits are near-instant.
The Enrichment Cache
Every successful provider response is written to EnrichmentCache keyed on email hash (plus provider, so different providers have their own cache slots per email).
When a later job requests the same email from the same provider, the cache returns the stored response if it is fresher than the cache TTL. Default TTL is 90 days. Beyond that the data is considered stale and the provider is called fresh.
Three things to know about the cache.
It is workspace-scoped by default. The same email enriched by two different workspaces on the same NimbusOS instance consumes two provider lookups. This is intentional: cross-workspace cache sharing would violate isolation in agency contexts.
The cache is bypassable. Setting force_refresh=true on an enrichment job ignores the cache and calls the provider fresh. Useful for contacts flagged as stale or when the provider has updated their data recently.
The cache records a confidence score. Providers return confidence bands on their data; the cache preserves them. A match with confidence below 60 is usable but flagged as low quality in the contact detail.
BYOK: Bring Your Own Key
Every enrichment provider supports BYOK. You paste your own API key in Integrations -> Provider -> Credentials, and enrichment credits burn from your account with the provider rather than a shared NimbusOS pool.
Credentials are Fernet-encrypted at rest. The provider key is workspace-scoped, so agency sub clients each bring their own keys.
BYOK has three advantages.
Cost transparency. You see every credit used in your provider dashboard. No markup from NimbusOS.
Compliance. Some enterprise contracts require direct vendor relationships. BYOK gives you one.
Capacity. Your account's rate limit and volume tier are yours. NimbusOS does not pool or throttle.
BYOK does require the operational overhead of managing the provider account. For small teams the managed option (NimbusOS pools credits and charges per-lookup) is often simpler.
Waterfall Enrichment
Clay's original feature is waterfall enrichment. NimbusOS has its own waterfall mode that you configure in enrichment job settings.
A waterfall job specifies an ordered list of providers. For each contact, the platform calls provider 1 first. If provider 1 returns a hit, the platform stops and writes the data. If provider 1 misses, the platform calls provider 2. And so on.
This maximizes coverage while minimizing cost. Apollo first, Clearbit second, Hunter third is a common setup because Apollo has the highest hit rate in SMB and Clearbit picks up what Apollo misses in enterprise. Hunter fills the long tail.
Waterfall mode writes the first successful provider's data to the contact. Subsequent providers in the order are not called for that contact.
Monthly Usage Tracking
Every enrichment job updates EnrichmentUsage rows: provider, workspace, month, credits used, cache hits, total cost in USD.
The Enrichment Usage dashboard visualizes this over time. Common views:
Cost by provider. Where is the enrichment budget going.
Hit rate by provider. Which provider is actually returning useful data.
Cache hit rate. How much are you re-enriching contacts you already have data for.
Coverage by field. Per field (industry, employee count, phone), what percent of contacts have data.
Cache hit rate under 30 percent usually means you are enriching too aggressively or not using the cache bypass rules correctly. Coverage by field under 50 percent on a critical field means the provider choice is wrong for your target market.
What Gets Enriched
Enrichment writes to both Contact and Company rows. Fields that most providers return:
Contact. First name, last name, title, seniority, department, LinkedIn URL, phone, mobile, location.
Company. Name, domain (canonicalized), industry, employee count, revenue band, headquarters location, founded year, tech stack, funding status, LinkedIn URL, Twitter URL, primary CRM tool, primary outbound tool.
Tech stack data is high-signal and high-variance. Different providers detect different tools. Clearbit is strong on marketing tools, PDL is strong on sales tools, BuiltWith (indirect through Clay) is strong on general web tools.
Enrichment at Import vs Later
The import pipeline has an optional enrichment step. Two patterns.
Enrich at import. Every imported contact gets a provider lookup immediately. Pros: contact is immediately ready to score and segment. Cons: you pay to enrich every contact including low-tier ones you will never send to.
Enrich after scoring. Import, score, segment to tier A and B, then enrich only those. Pros: lower cost because you only enrich the slice you actually care about. Cons: tier and score are less accurate during the scoring pass because enrichment data is missing.
For large lists (over 10k contacts) the after-scoring pattern is usually better economics. For small lists (under 1k) the at-import pattern is simpler.
Triggering Manual Enrichment
Outside of imports and scheduled jobs, you can trigger enrichment from:
- Contact detail page (single contact, immediate)
- Segment detail page (all members, async job)
- Contact list bulk action (selected rows, async job)
- API (
POST /api/v1/contacts/:id/enrichor batch endpoint)
All paths produce an EnrichmentJob under the hood. Manual triggers default to waterfall across configured providers unless you specify one.
Stale Refresh
The enrichment cache has a TTL of 90 days by default. Beyond that, contacts are flagged stale. The Stale Contacts dashboard lists them.
You can refresh stale contacts in bulk from the dashboard. A refresh runs a waterfall enrichment on every stale contact; cache hits skip for contacts whose data is still fresh under a shorter TTL you set per job.
Some workspaces schedule a weekly refresh of stale contacts. The AutomationRule trigger on_schedule with a condition enrichment_status == 'stale' automates this.
Compliance
Enrichment data is subject to GDPR and CCPA rules. Three guardrails.
First, the suppression list blocks enrichment on suppressed emails. If a contact has opted out, no provider lookup happens.
Second, the data retention policy applies. A workspace with a 365-day retention policy deletes enrichment data on contacts older than 365 days.
Third, the GDPR deletion flow removes enrichment cache entries for the deleted email across every provider.
Troubleshooting
"Enrichment runs but fills very few fields"
Wrong provider for the market. Apollo is weak on European and APAC data; Clearbit or Cognism is stronger there. Check coverage by field in the usage dashboard.
"Same contacts keep running through provider, not cache"
The cache TTL is expired or force_refresh is being set. Check the enrichment job configuration. If you are using the API, check that the force_refresh parameter is not being sent.
"Provider returned data but the contact was not updated"
Enrichment write rules may be blocking the update. If the contact already had a value for the field, the default is to preserve the existing value. Changing to overwrite mode in job settings updates the field.
"Provider reports quota exhausted"
Your BYOK credit balance is zero, or the NimbusOS pooled quota (if on managed plan) is exhausted for the month. Refill the provider account or upgrade the NimbusOS plan.
Frequently Asked Questions
Can I enrich a contact without a company domain?
Most providers need either email or domain to match. Contacts with only first name and last name will mostly miss. Enrichment is far more successful with at least email and ideally email plus domain.
Do providers share data with NimbusOS?
No. Each provider API call is direct from the NimbusOS worker to the provider. The provider does not send data to any shared NimbusOS pool; it returns to your workspace only.
How do I choose between Apollo and Clearbit?
Apollo is usually better for US SMB and mid-market. Clearbit is usually better for enterprise and non-US. For mixed markets, a waterfall with Apollo first and Clearbit second is the typical setup.
Does enrichment affect lead score?
Yes. Most scoring models have fit components that reference industry, company size, and tech stack. Enrichment data directly affects fit score.
What to Read Next
Useful next pages after this one: BYOK (Bring Your Own Key) for credential management across providers, Email Verification for the deliverability-focused sibling of enrichment, and Importing Contacts for where enrichment fits in the intake pipeline.