Build a Data Enrichment Pipeline

In this guide, you'll build a data enrichment pipeline that:

• Enriches new contacts in real-time as they enter your system
• Processes existing records in batch (up to 500K at a time)
• Receives results via webhooks for async workflows
• Handles errors and retries gracefully

We'll use the Enrich TypeScript SDK (@enrich.so/sdk) and Node.js. The same concepts apply if you're using the Go SDK or raw REST API calls.

Before starting, you'll need:

• Node.js 18+ installed
• An Enrich API key (sign up at dash.enrich.so for 100 free credits)
• Basic familiarity with TypeScript and async/await

Install the SDK:

npm install @enrich.so/sdk

The simplest enrichment flow is a synchronous API call. You send an identifier and get back enriched data in under 200ms. Enrich's Email Finder and other endpoints all support this pattern.

import Enrich from '@enrich.so/sdk';
const enrich = new Enrich('YOUR_API_KEY');
// Enrich a person by email
const person = await enrich.person.find({
  email: 'sarah@techcorp.io'
});
console.log(person.name);    // Sarah Chen
console.log(person.title);   // VP of Engineering
console.log(person.company); // TechCorp

Use this approach when you need results immediately like form submissions, CRM record creation, or chatbot conversations. The API returns a complete profile with name, title, company, social links, and a confidence score.

For enriching existing databases or large imports, use batch processing. Submit up to 500,000 records in a single request.

// Submit a batch
const batch = await enrich.emailFinder.batch({
  records: contacts.map(c => ({
    firstName: c.firstName,
    lastName: c.lastName,
    domain: c.companyDomain,
  })),
  webhookUrl: 'https://your-app.com/webhooks/enrich'
});
console.log(batch.batchId); // Use this to check status

Batch jobs run asynchronously. You can poll for status or, or better, set up a webhook to receive results as they complete.

Webhooks notify your application when enrichment results are ready. Set up an endpoint to receive them:

// Express webhook handler
app.post('/webhooks/enrich', (req, res) => {
  const { event, batchId, data } = req.body;
  if (event === 'enrichment.completed') {
    // Process each result
    for (const result of data.results) {
      await saveToDatabase(result);
    }
  }
  res.status(200).send('OK');
});

Webhooks are the recommended approach for batch processing. They eliminate polling, reduce API calls, and let you process results as they arrive rather than waiting for the entire batch to finish.

Production pipelines need to handle failures gracefully:

async function enrichWithRetry(
  email: string,
  maxRetries = 3
): Promise<Person | null> {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      return await enrich.person.find({ email });
    } catch (error) {
      if (error.status === 429) {
        // Rate limited. Wait and retry
        await sleep(1000 * attempt);
        continue;
      }
      if (error.status === 404) {
        // No match found. Not an error
        return null;
      }
      throw error; // Unexpected error
    }
  }
  return null;
}

• Rate limiting (429): Back off exponentially and retry
• Not found (404): The person wasn't matched, handle gracefully
• Server errors (5xx): Retry with backoff, then alert if persistent

With this foundation, you can extend your pipeline:

• Add email validation before sending outreach, catch invalid addresses at enrichment time
• Schedule re-enrichment to catch job changes and updated phone numbers
• Use the MCP server to let AI agents trigger enrichment autonomously
• Set up monitoring to track match rates, latency, and credit usage via the dashboard at dash.enrich.so

Check the full API documentation at doc.enrich.so for all available endpoints, parameters, and response fields.