Enrich companies

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:

Field	Meaning
`lastEnrichmentStartedAt`	When the most recent run began.
`lastEnrichedAt`	When 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.

Collect the records

Add the companies you want to enrich to a list.

Enrich the list

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

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.

Core tasks

API essentials

Trigger enrichment for one company

Know when enrichment is done

Enrich in bulk

Next steps

Build a list

Automate it

​Trigger enrichment for one company

​Know when enrichment is done

​Enrich in bulk

​Next steps

Build a list

Automate it

Trigger enrichment for one company

Know when enrichment is done

Enrich in bulk

Next steps