API Reference

Q: What authentication model does the API use?

All endpoints use Bearer token authentication. Requests should include Authorization headers and idempotency keys for write safety.

Q: How do I choose between transactional, batch, and file-scale match modes?

Use transactional for single-record low-latency checks, batch for smaller grouped jobs, and file-scale for large async workloads.

Q: Where can I debug failed requests?

Use request IDs, correlation IDs, and structured error payload fields to trace failures and retry safely.

Q: Is there a quick integration path from docs to workflow execution?

Yes. Use API docs for endpoint contracts, then pair with integrations and CLI docs for orchestration and downstream activation.

Base URL:https://api.foundryops.io

FoundryOps API Reference

Complete technical documentation for integrating FoundryOne™ entity resolution into your applications and data pipelines.

Bearer token auth

OpenAPI 3.0 spec

Postman collection

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

Required Headers

Authorization: Bearer your_api_key
Content-Type: application/json
X-Idempotency-Key: unique-request-id  # Recommended for POST requests

X-Request-Id

Returned on every response for tracing

X-RateLimit-*

Remaining, limit, and reset headers

X-Credits-Remaining

Current credit balance (or -Simulated)

Match Modes

Three modes optimized for different workloads. All return match scores, confidence levels, and reason chips.

Transactional (Real-time)

Use case: Lead routing, inline product UX

Limits: 1 record, ~128KB, <2s latency target

POST /api/v2/match/record

curl -X POST "https://api.foundryops.io/api/v2/match/record" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: rec-$(uuidgen)" \
  -d '{
    "snapshot_id": "dss_snapshot1",
    "record": {
      "company_name": "Acme Inc",
      "domain": "acme.com"
    },
    "options": {
      "profile": "balanced",
      "threshold": 0.8,
      "top_n": 5,
      "return_explanations": true
    }
  }'

Available Profiles:

high_precisionbalancedhigh_recallleads_to_accounts

Batch

Use case: Periodic syncs, bulk matching jobs

Limits: 100 records, 512KB max

POST /api/v2/match/batch

curl -X POST "https://api.foundryops.io/api/v2/match/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-$(uuidgen)" \
  -d '{
    "snapshot_id": "dss_snapshot1",
    "records": [
      {"company_name": "Acme Inc", "domain": "acme.com"},
      {"company_name": "Globex Corp", "domain": "globex.com"}
    ],
    "options": {"profile": "balanced", "threshold": 0.7},
    "callback_url": "https://your-app.com/webhook/match-complete"
  }'

# Response:
{
  "job_id": "job_01H8X9Y2Z3...",
  "status": "queued",
  "poll_url": "/api/v2/jobs/job_01H8X9Y2Z3...",
  "results_url": "/api/v2/jobs/job_01H8X9Y2Z3.../results"
}

File-Scale

Use case: Warehouse deduplication, bulk processing

Limits: No hard row cap, CSV/Parquet input

POST /api/v2/match/files

# Step 1: Get presigned upload URL
curl -X POST "https://api.foundryops.io/api/v2/uploads/presign?purpose=match" \
  -H "Authorization: Bearer $API_KEY"

# Response: {"upload_url": "https://storage.../...", "storage_key": "sk_..."}

# Step 2: Upload your file
curl -X PUT "$UPLOAD_URL" -T leads.csv

# Step 3: Submit file match job
curl -X POST "https://api.foundryops.io/api/v2/match/files" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "dss_snapshot1",
    "source_key": "sk_...",
    "options": {"profile": "balanced"},
    "output_format": "parquet"
  }'

Company Enrichment

FoundryGraph

Standardize and enrich company records with firmographics from FoundryGraph's 220M+ company knowledge graph. Use as a pre-match utility to clean data or as a standalone backfill service.

Lookup (Single Company)

Use case: Real-time form enrichment, lead standardization

Limits: 1 company per request, ~1KB response

GET /api/v2/enrich/company/lookup

# By domain
curl "https://api.foundryops.io/api/v2/enrich/company/lookup?domain=microsoft.com" \
  -H "Authorization: Bearer $API_KEY"

# OR by Wikidata ID
curl "https://api.foundryops.io/api/v2/enrich/company/lookup?wikidata_id=Q2283" \
  -H "Authorization: Bearer $API_KEY"

# Response:
{
  "wikidata_id": "Q2283",
  "canonical_name": "Microsoft Corporation",
  "aliases": ["Microsoft", "MSFT", "Microsoft Corp"],
  "domains": ["microsoft.com", "xbox.com", "github.com"],
  "parent_org": null,
  "subsidiaries": [
    {"wikidata_id": "Q95339459", "name": "GitHub, Inc."},
    {"wikidata_id": "Q213660", "name": "LinkedIn"}
  ],
  "country_code": "US",
  "industry": "Computer Software",
  "employee_count": 221000,
  "stock_ticker": "MSFT",
  "lei": "INR2EJN1ERAN0W5ZP974",
  "sources": ["wikidata", "gleif", "sec_edgar"]
}

Not Found Handling:

{
  "not_found": true,
  "input": "microsft.com",  // typo
  "suggestions": [
    {"domain": "microsoft.com", "confidence": 0.95}
  ]
}

Batch Enrichment

Use case: Backfill CRM accounts, standardize lead lists

Limits: 100 companies per request, ~100KB response

POST /api/v2/enrich/company/batch

curl -X POST "https://api.foundryops.io/api/v2/enrich/company/batch" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"id": "lead-123", "domain": "microsoft.com"},
      {"id": "lead-456", "domain": "apple.com"},
      {"id": "lead-789", "domain": "unknown-startup.io"}
    ]
  }'

# Response:
{
  "enriched": [
    {
      "id": "lead-123",
      "company": {
        "wikidata_id": "Q2283",
        "canonical_name": "Microsoft Corporation",
        "parent_org": null,
        "country_code": "US",
        "industry": "Computer Software"
      }
    },
    {
      "id": "lead-456",
      "company": {
        "wikidata_id": "Q312",
        "canonical_name": "Apple Inc.",
        "parent_org": null,
        "country_code": "US",
        "industry": "Consumer Electronics"
      }
    }
  ],
  "not_found": [
    {
      "id": "lead-789",
      "domain": "unknown-startup.io",
      "reason": "No match in knowledge graph"
    }
  ]
}

File-Scale Enrichment

Use case: Enrich 10K+ accounts, warehouse backfill

Limits: No hard row cap, CSV/Parquet input

POST /api/v2/enrich/company/file

# Step 1: Get presigned upload URL
curl -X POST "https://api.foundryops.io/api/v2/uploads/presign?purpose=enrichment" \
  -H "Authorization: Bearer $API_KEY"

# Response: {"upload_url": "https://storage.../...", "storage_key": "sk_..."}

# Step 2: Upload CSV with domain column
curl -X PUT "$UPLOAD_URL" -T accounts.csv

# Step 3: Submit enrichment job
curl -X POST "https://api.foundryops.io/api/v2/enrich/company/file" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_key": "sk_...",
    "domain_column": "website",
    "output_format": "csv"
  }'

# Response:
{
  "job_id": "job_01H9...",
  "status": "queued",
  "poll_url": "/api/v2/jobs/job_01H9..."
}

# Output: Original file + enriched columns
# account_id, website, canonical_name, parent_org, country_code, industry, employee_count

Coverage

220M+ companies (Wikidata, GLEIF, SEC, OpenCorporates)
69K+ domain mappings curated, 4.9M+ company profiles
52K+ parent relationships (GLEIF legal hierarchy)
Weekly delta sync for fresh data

Pricing

0.1 credits per lookup

1,000 enrichments = 100 credits ≈ $1
10,000 enrichments = 1,000 credits ≈ $10

Included by tier:

FREE: 100/month
PRO: 1,000/month
ENTERPRISE: 10,000/month

Common Use Cases

1. Pre-Match Standardization

Enrich leads with canonical names and parent companies before matching to accounts → improves match accuracy by 30%+

Workflow

# 1. Enrich incoming lead
POST /api/v2/enrich/company/lookup?domain=github.com
# Returns: "GitHub, Inc." (subsidiary of Microsoft)

# 2. Match with clean data
POST /api/v2/match/record
{
  "record": {
    "company_name": "GitHub, Inc.",
    "parent_company": "Microsoft Corporation"
  }
}

2. Account Backfill

Add missing parent company, industry, and headcount data to 10,000+ existing CRM accounts

Example

# Upload accounts.csv with columns: account_id, website
POST /api/v2/enrich/company/file

# Download enriched.csv with added columns:
# canonical_name, parent_org, country, industry, employee_count, lei

3. Real-Time Form Enrichment

Auto-populate company details when user enters domain in web form → reduce form friction

Example

// User types "acme.com" in signup form
GET /api/v2/enrich/company/lookup?domain=acme.com

// Auto-fill: Company Name, Industry, Employee Count, HQ Country

Response Fields Reference

wikidata_idUnique company identifier (e.g., Q2283)

canonical_nameOfficial legal name

aliasesArray of alternative names/brands

domainsAll known website domains

parent_orgUltimate parent company (null if parent)

subsidiariesArray of owned companies

country_codeHQ country (ISO 3166-1 alpha-2)

industryPrimary industry classification

employee_countLatest headcount (nullable)

stock_tickerTicker symbol if publicly traded

leiLegal Entity Identifier (GLEIF)

sourcesData provenance array

Dataset API v2

Labs

Create, append, and activate master datasets with schema enforcement, type coercion, DQ summaries, and reject artifacts.

Create Dataset

POST /api/v2/datasets

curl -X POST "https://api.foundryops.io/api/v2/datasets" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Master Data",
    "schema": {
      "customer_id": "int",
      "company_name": "string",
      "email": "string",
      "created_at": "timestamp"
    }
  }'

# Response:
{
  "dataset_id": "ds_01H8...",
  "name": "Customer Master Data",
  "schema": {...},
  "created_at": "2024-01-15T10:00:00Z"
}

Append Records

POST /api/v2/datasets/{dataset_id}/append

curl -X POST "https://api.foundryops.io/api/v2/datasets/ds_01H8.../append" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "records": [
      {"customer_id": 1, "company_name": "Acme", "email": "[email protected]", "created_at": "2024-01-01T00:00:00Z"},
      {"customer_id": 2, "company_name": "Globex", "email": "[email protected]", "created_at": "2024-01-02T00:00:00Z"}
    ]
  }'

# Response includes DQ summary:
{
  "snapshot_id": "dss_...",
  "accepted": 2,
  "rejected": 0,
  "coercions": {"timestamp": 2},
  "null_pct": {"email": 0.0}
}

Activate Snapshot

POST /api/v2/datasets/{dataset_id}/activate

curl -X POST "https://api.foundryops.io/api/v2/datasets/ds_01H8.../activate" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot_id": "dss_..."}'

Supported Types

stringintfloatbooltimestamp

Rejected rows are written to NDJSON.gz artifacts for review.

Uploads & Jobs

Uploads

Get presigned URLs for file uploads. Supports CSV, Parquet, and NDJSON.

POST /api/v2/uploads/presign?purpose=dataset|match

Jobs

All async endpoints return job_id. Poll for status or use callback_url.

GET /api/v2/jobs/{job_id}

Poll Job Status

curl "https://api.foundryops.io/api/v2/jobs/job_01H8X9Y2Z3..." \
  -H "Authorization: Bearer $API_KEY"

# Response:
{
  "job_id": "job_01H8X9Y2Z3...",
  "status": "running",  // queued | running | completed | failed
  "progress": {
    "processed": 42000,
    "total": 100000,
    "percentage": 42.0
  },
  "eta_seconds": 130
}

Billing & Usage

Shadow Mode (default)

Usage metered but no credits debited. Check costs via X-Credits-Remaining-Simulated header.

Enforced Mode

Credits debited per operation. Returns 402 with top-up Link header when balance is insufficient.

Rate Limits by Tier

QPS · FREE

QPS · PRO

QPS · ENTERPRISE

429 responses include X-Concurrency-Limit and X-Queue-Depth headers

Security, Observability & Errors

Security

RBAC scopes on datasets, jobs, webhooks
Full audit trail for all mutations
SOC 2 Type II ready

Observability

OTEL tracing with W3C context propagation
Prometheus /metrics endpoint
Structured JSON logging

Error Response Format

Error Model

{
  "error": {
    "code": "INVALID_SCHEMA",
    "message": "Field 'customer_id' expected int, got string",
    "details": {
      "field": "customer_id",
      "expected": "int",
      "received": "string"
    }
  },
  "correlation_id": "7c3b-...",
  "request_id": "req_abc123"
}

// Common error codes:
// INVALID_SCHEMA, PAYLOAD_TOO_LARGE, RATE_LIMIT,
// INSUFFICIENT_CREDITS, UNAUTHORIZED, DATASET_NOT_FOUND

Data retention: Artifacts 24h, decision logs 30d

SDKs & Tools

Python

pip install foundryops

from foundryops import FoundryOps

client = FoundryOps(api_key="...")
result = client.match.record(
    snapshot_id="dss_...",
    record={"company_name": "Acme"}
)

TypeScript

npm i @foundryops/sdk

import { FoundryOps } from "@foundryops/sdk";

const client = new FoundryOps({
  apiKey: process.env.API_KEY
});

CLI & Postman

CLI wraps the Python SDK for quick submits and billing checks.

Postman collection available in the developer portal.

API Docs FAQ

What authentication model does the API use?

All endpoints use Bearer token authentication. Requests should include Authorization headers and idempotency keys for write safety.

How do I choose between transactional, batch, and file-scale match modes?

Use transactional for single-record low-latency checks, batch for smaller grouped jobs, and file-scale for large async workloads.

Where can I debug failed requests?

Use request IDs, correlation IDs, and structured error payload fields to trace failures and retry safely.

Is there a quick integration path from docs to workflow execution?

Yes. Use API docs for endpoint contracts, then pair with integrations and CLI docs for orchestration and downstream activation.

Related docs: Integrations | CLI Reference | Documentation Hub

Ready to Integrate?

Join the early access program and start building with FoundryOps API.

Request API Access Back to Overview