Back to Overview|

API Reference

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

v2

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, enrichment 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"
  }'

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": "info@acme.com", "created_at": "2024-01-01T00:00:00Z"},
      {"customer_id": 2, "company_name": "Globex", "email": "info@globex.com", "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

2
QPS · FREE
10
QPS · PRO
50
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.

Ready to Integrate?

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

Request API AccessBack to Overview