Skip to main content
Enrichment fills in what you don’t already know — firmographics, financials, headcount, and signals — by combining AI with data providers. This guide is the task-oriented companion to the enrichment concept: how to trigger it, know when it’s done, and run it across many records.

​
Trigger enrichment for one company

Enrichment runs asynchronously. Triggering it returns immediately; the enriched values appear on the record once processing completes. 
curl -X POST https://api.metal.ai/v1/companies/665f1c2a9b1e4a0012a3b4c5/enrich \
  -H "x-metal-client-id: $METAL_CLIENT_ID" \
  -H "x-metal-api-key: $METAL_API_KEY"
Create a company with at least a canonicalName — and a website when you have one — before enriching. The more identifying detail you provide, the more accurate the result.

​
Know when enrichment is done

Don’t hold a request open waiting for results. Instead, poll the company and compare two timestamps:
FieldMeaning
lastEnrichmentStartedAtWhen the most recent run began.
lastEnrichedAtWhen enrichment last completed and wrote values.
A run is still in progress while lastEnrichmentStartedAt is newer than lastEnrichedAt. 
import os
import time
import requests

BASE = "https://api.metal.ai/v1"
headers = {
    "x-metal-client-id": os.environ["METAL_CLIENT_ID"],
    "x-metal-api-key": os.environ["METAL_API_KEY"],
}

def wait_for_enrichment(company_id, timeout=300, interval=10):
    requests.post(f"{BASE}/companies/{company_id}/enrich", headers=headers)
    deadline = time.time() + timeout
    while time.time() < deadline:
        company = requests.get(f"{BASE}/companies/{company_id}", headers=headers).json()["data"]
        started = company.get("lastEnrichmentStartedAt")
        finished = company.get("lastEnrichedAt")
        if finished and (not started or finished >= started):
            return company
        time.sleep(interval)
    raise TimeoutError(f"Enrichment for {company_id} did not finish in {timeout}s")
Prefer not to poll? Configure a webhook trigger so Metal notifies your system when enrichment completes.

​
Enrich in bulk

Looping enrich one company at a time works, but it’s slow and burns through rate limits. To enrich many records efficiently, add them to a list and enrich at the list level — Metal computes enriched columns across every entry.
1

Collect the records

Add the companies you want to enrich to a list.
2

Enrich the list

Trigger enrichment at the list level so it fans out across all entries.
3

Read results

Read the list entries to pull enriched values for every company at once.

​
Next steps

Build a list

Group records to enrich and analyze them in bulk.

Automate it

Run a workflow that enriches and screens targets end to end.