Introduction

The Company Enrichment API turns a domain into structured company data you can use across your signup flow, CRM, and analytics. In this post, we cover inputs, endpoints, response fields, caching, error handling, and production-ready Node.js snippets you can paste into your app today.

What this API does

Given a domain (e.g., acme.com), the API returns normalized company details such as name, website, logo, industry, employee range, country, and social links. You can call it synchronously during form submit, asynchronously in a background job, or as part of a nightly backfill.

Endpoint overview

Method	Path	Purpose	Notes
GET	`/enrich?domain={domain}`	Return structured company data	Primary endpoint; JSON response
GET	`/logo/{domain}?size=128&format=png`	Return logo image directly	Great for UI thumbnails

Authentication

Depending on plan, requests may require an API key via header. Example:

curl -H 'Authorization: Bearer YOUR_API_KEY' \n  '[https://api.hellobrand.dev/enrich?domain=acme.com](https://api.hellobrand.dev/enrich?domain=acme.com)'

Sample response

Fields can evolve; rely on presence checks. Example payload:

{
  "name": "Acme Inc",
  "domain": "acme.com",
  "website": "[https://www.acme.com",
](https://www.acme.com",
)  "logo": "[https://api.hellobrand.dev/logo/acme.com?format=png&size=128",
](https://api.hellobrand.dev/logo/acme.com?format=png&size=128",
)  "industry": "Software",
  "employees": { "min": 51, "max": 200 },
  "country": "US",
  "social": { "linkedin": "[https://www.linkedin.com/company/acme](https://www.linkedin.com/company/acme)" }
}

Node.js quick start

Works on Node 18+ using native fetch. Replace YOUR_API_KEY if your plan requires it.

const API = '[https://api.hellobrand.dev';
const](https://api.hellobrand.dev';
const) KEY = process.env.HB_API_KEY; // optional depending on plan

async function enrichDomain(domain) {
  const url = `${API}/enrich?domain=${encodeURIComponent(domain)}`;
  const res = await fetch(url, { headers: KEY ? { Authorization: `Bearer ${KEY}` } : {} });

  if (res.status === 404) return null; // unknown domain
  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('retry-after') || 2);
    await new Promise(r => setTimeout(r, retryAfter * 1000));
    return enrichDomain(domain); // simple retry
  }
  if (!res.ok) throw new Error(`Enrich failed: ${res.status}`);
  return res.json();
}

// Example usage
(async () => {
  const data = await enrichDomain('acme.com');
  console.log(data);
})();

Server route example (lead intake)

import express from 'express';
const app = express();
app.use(express.json());

app.post('/signup', async (req, res) => {
  const { email, companyWebsite } = req.body;
  const domain = companyWebsite?.replace(/^https?:///, '').split('/')[0] || email?.split('@')[1];

  let enrichment = null;
  if (domain) {
    try { enrichment = await enrichDomain(domain); } catch (e) { /* log and continue */ }
  }

  // Map only fields you will use
  const account = {
    email,
    domain,
    companyName: enrichment?.name,
    industry: enrichment?.industry,
    employeesMin: enrichment?.employees?.min,
    employeesMax: enrichment?.employees?.max,
    logo: enrichment?.logo
  };

  // TODO: persist to DB & route to a sales queue
  return res.status(201).json({ ok: true, account });
});

app.listen(3000, () => console.log('listening on :3000'));

Bulk enrichment (CSV backfill)

Backfill existing records in batches with simple retry and rate-limit handling.

import { readFile, writeFile } from 'node:fs/promises';

async function backfill(csvPath) {
  const lines = (await readFile(csvPath, 'utf8')).trim().split('
');
  const header = lines.shift().split(',');
  const domainIdx = header.indexOf('domain');
  const out = [header.concat(['companyName','industry','employeesMin','employeesMax','logo']).join(',')];

  for (const line of lines) {
    const cols = line.split(',');
    const domain = cols[domainIdx];
    const data = domain ? await enrichDomain(domain) : null;

    cols.push(
      data?.name || '',
      data?.industry || '',
      String(data?.employees?.min || ''),
      String(data?.employees?.max || ''),
      data?.logo || ''
    );
    out.push(cols.join(','));
    await new Promise(r => setTimeout(r, 150)); // light pacing
  }

  await writeFile(csvPath.replace(/.csv$/, '.enriched.csv'), out.join('
'));
}

Error handling & retries

404: Domain unknown; store nulls and allow a manual review.
429: Respect Retry-After; use exponential backoff with jitter.
5xx: Retry with capped backoff (e.g., 250ms → 500ms → 1s → 2s; max 4 attempts).
Network: Wrap calls in a timeout (e.g., 8s) and treat timeouts as retryable.

Caching & freshness

Edge cache: Put a CDN in front of your app and cache successful responses for 7–30 days.
ETag/Last-Modified: If provided, use conditional requests to avoid re-downloading unchanged data.
Re-enrich triggers: Allow users to refresh a record after a rebrand or domain change.

Field mapping tips

Store root domain only (no protocol or path); lowercase and strip www.
Use ranges for employees/revenue; avoid overfitting logic to point estimates.
Keep a source and lastRefreshedAt column for auditing.

Security & compliance

Pass API keys via headers; never hardcode them in client-side code.
Collect only the fields you actually need; document retention policy.
Honor deletion requests by removing linked enrichment data.

UI helpers

Display the logo via the dedicated logo endpoint for crisp avatars and partner grids:

FAQ

Is the API real-time?

Cached domains resolve instantly. First-time lookups may take slightly longer; cache results for 7–30 days.

Which input is best?

A verified domain is ideal. If you only have an email, derive the domain from it.

Do I need to store the logo?

Prefer hot-linking via the logo endpoint with caching headers; store only if you need full offline control.

Conclusion

The Company Enrichment API gives your SaaS immediate context from a single domain. Implement a thin Node.js wrapper with retries, cache aggressively, and map only the fields you use. The result: shorter forms, cleaner CRM data, and smarter routing.

Company Enrichment API: How It Works + Code Examples (Node.js)

Ready to get started with HelloBrand API?