The KnowFirm batch enrich API lets you resolve up to 100 businesses in a single request. This guide shows how to read a CSV of business names or identifiers, enrich them via the API, and write the results back to a file.

Prerequisites

• A KnowFirm API key (free tier works for small batches; Starter plan and above for production volumes)
• A CSV file with a column of business names, EINs, CIKs, or LEIs

How batch enrich works

POST /v1/enrich accepts an items array where each item can identify a business by name, ein, cik, or lei. The API resolves each item against the KnowFirm warehouse and returns matched entities with confidence scores and per-field provenance.

Each resolved record costs 1 credit. Unresolved items (no match) are returned with null entity and are not billed.

Node.js example

import fs from "node:fs";

const API_KEY = process.env.KNOWFIRM_KEY;
const BATCH_SIZE = 100; // API maximum per request

// Read CSV (assumes a "name" column; adjust for your format)
const lines = fs.readFileSync("businesses.csv", "utf8").trim().split("\n");
const header = lines[0].split(",");
const nameIdx = header.indexOf("name");
const rows = lines.slice(1).map((l) => l.split(","));

const results = [];

for (let i = 0; i < rows.length; i += BATCH_SIZE) {
  const batch = rows.slice(i, i + BATCH_SIZE);
  const items = batch.map((r) => ({ name: r[nameIdx].trim() }));

  const res = await fetch("https://api.knowfirm.com/v1/enrich", {
    method: "POST",
    headers: {
      "X-API-Key": API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ items }),
  });

  const data = await res.json();
  results.push(...data.results);
}

// Write enriched CSV
const out = ["name,ein,lei,confidence,sources"];
for (const r of results) {
  const e = r.entity;
  out.push(
    [
      r.query?.name ?? "",
      e?.ein ?? "",
      e?.lei ?? "",
      e?.confidence ?? "",
      e?.sources?.join(";") ?? "",
    ].join(","),
  );
}
fs.writeFileSync("enriched.csv", out.join("\n"));
console.log(`Enriched ${results.length} records`);

Python example

import csv, os, json, urllib.request

API_KEY = os.environ["KNOWFIRM_KEY"]
BATCH_SIZE = 100

# Read CSV
with open("businesses.csv") as f:
    reader = csv.DictReader(f)
    rows = list(reader)

results = []

for i in range(0, len(rows), BATCH_SIZE):
    batch = rows[i : i + BATCH_SIZE]
    items = [{"name": r["name"].strip()} for r in batch]

    req = urllib.request.Request(
        "https://api.knowfirm.com/v1/enrich",
        data=json.dumps({"items": items}).encode(),
        headers={
            "X-API-Key": API_KEY,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(req) as resp:
        data = json.loads(resp.read())
    results.extend(data["results"])

# Write enriched CSV
with open("enriched.csv", "w", newline="") as f:
    writer = csv.writer(f)
    writer.writerow(["name", "ein", "lei", "confidence", "sources"])
    for r in results:
        e = r.get("entity") or {}
        writer.writerow([
            (r.get("query") or {}).get("name", ""),
            e.get("ein", ""),
            e.get("lei", ""),
            e.get("confidence", ""),
            ";".join(e.get("sources", [])),
        ])

print(f"Enriched {len(results)} records")

Tips

• Batch size: the API accepts up to 100 items per request. For larger files, paginate as shown above.
• Identifiers over names: when you have an EIN, CIK, or LEI, use it instead of a name — identifier lookups have higher resolution rates and are unambiguous.
• Rate limits: the API allows 120 requests per minute. For large enrichments (10K+ rows), add a short delay between batches or watch the X-RateLimit-Remaining header.
• Costs: each resolved record costs 1 credit. Unresolved items are free. Monitor your usage at Dashboard → Usage.

FAQ

How many businesses can I enrich in one request? Up to 100 items per POST /v1/enrich request. Paginate larger files in batches of 100.

What identifiers can I use for batch enrich? Each item can use name, ein, cik, or lei. You can mix identifier types in the same batch.

What happens if a business is not found? The item is returned with a null entity and is not billed. Check the error field for the reason (e.g. not_found).

Is batch enrich available on the Free plan? Batch enrich requires the Starter plan or above. Free-tier accounts can use single lookups via GET /v1/business.