Choose the right contract before you write code.

PUBLIC COMPANYPROOF INTERFACES

One endpoint map, with no implied module routes.

These are the complete public endpoints currently supported. Officers, shareholders, hierarchy and financial data are returned only when present inside the consolidated profile; there are no public per-module routes in this version.

CAPABILITY BOUNDARY

Know what this contract does—and what it does not.

ADAPTIVE INTELLIGENCE API · ORCHESTRATION

Ask for intelligence when the schema can be dynamic.

The Adaptive Intelligence API requires a live key, accepts one self-contained question of 1–4,000 characters and streams Server-Sent Events. Use mode: "ai" for a written answer plus tool data, or mode: "data" for data-oriented output.

const response = await fetch(
  "https://companyproof.ai/v2/intelligence/query",
  {
    method: "POST",
    headers: {
      "Authorization": "Bearer " + process.env.COMPANYPROOF_API_KEY,
      "Content-Type": "application/json",
      "Accept": "text/event-stream"
    },
    body: JSON.stringify({
      query: "Find Acme Holdings in GB and show its directors and financials",
      mode: "ai"
    })
  }
);

// Consume response.body as Server-Sent Events.

The initial HTTP request can fail with the normal JSON error envelope. Once streaming begins, errors arrive as SSE error events. The server does not promise replay IDs; retry the complete request with your own correlation ID. Clients must ignore unknown event types for forward compatibility.

QUICK START

Verify the documented sample.

Create a test key in your account. Test keys work only with the fictional CompanyProof Sandbox Limited fixture in GB, and they cannot enable monitoring or retrieve live profiles.

curl --request POST \
  --url https://companyproof.ai/v2/claims/verify \
  --header "Authorization: Bearer $COMPANYPROOF_TEST_KEY" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: verify_01J62E8A" \
  --data '{
    "company": {
      "name": "CompanyProof Sandbox Limited",
      "country": "GB"
    },
    "claims": [
      { "field": "status", "published": "Active" },
      { "field": "incorporation_date", "published": "2021-01-15" }
    ],
    "monitor": false
  }'

A newly created proof returns 201 Created. An idempotent replay returns 200 OK with Idempotent-Replayed: true.

AUTHENTICATION

Use one CompanyProof credential.

API keys begin with cp_test_ or cp_live_. Send them from your server, store them in a secrets manager and rotate or revoke them from the account console. The full token is displayed only once.

MODEL CONTEXT PROTOCOL · COMPANYPROOF

Give agents typed CompanyProof company tools.

CompanyProof MCP uses stateless Streamable HTTP. It is intended for MCP clients that can send a custom Authorization header. Direct ChatGPT connection requires OAuth and is not yet offered; do not paste API keys into a prompt or an OAuth-only connector screen.

{
  "mcpServers": {
    "companyproof": {
      "type": "http",
      "url": "https://companyproof.ai/v2/mcp",
      "headers": {
        "Authorization": "Bearer ${COMPANYPROOF_API_KEY}"
      }
    }
  }
}

curl --request POST \
  --url https://companyproof.ai/v2/mcp \
  --header "Authorization: Bearer $COMPANYPROOF_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2026-07-28" \
  --header "Mcp-Method: server/discover" \
  --data '{
    "jsonrpc": "2.0",
    "id": "discover",
    "method": "server/discover",
    "params": {
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "companyproof-client", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

curl --request POST \
  --url https://companyproof.ai/v2/mcp \
  --header "Authorization: Bearer $COMPANYPROOF_TEST_KEY" \
  --header "Content-Type: application/json" \
  --header "Accept: application/json, text/event-stream" \
  --header "MCP-Protocol-Version: 2026-07-28" \
  --header "Mcp-Method: tools/call" \
  --header "Mcp-Name: verify_company_claims" \
  --data '{
    "jsonrpc": "2.0",
    "id": "verify",
    "method": "tools/call",
    "params": {
      "name": "verify_company_claims",
      "arguments": {
        "company": {
          "name": "CompanyProof Sandbox Limited",
          "country": "GB",
          "registration_number": "CP000001"
        },
        "claims": [
          { "field": "status", "published": "Active" }
        ],
        "monitor": false,
        "idempotency_key": "verify_agent_01J62E8A"
      },
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientInfo": { "name": "companyproof-client", "version": "1.0.0" },
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

1. 01
   server/discover

   Use current protocol version 2026-07-28. Send the matching MCP-Protocol-Version and Mcp-Method headers plus the protocol version, client identity and capabilities in params._meta. The result identifies CompanyProof and its supported versions.

2. 02
   tools/list

   Send Mcp-Method: tools/list and the same request metadata. The JSON result contains deterministic tool order, live input/output schemas, annotations and private cache hints.

3. 03
   tools/call

   Send Mcp-Method: tools/call and a matching Mcp-Name. Successful JSON results return typed structuredContent plus a JSON text fallback.

ENVIRONMENTS

Build safely in test, then issue a live key.

Test proofs are persisted in your ledger and use a separate 10-credit monthly test allowance. Search, profile, adaptive intelligence and the corresponding MCP read tools return 403 live_key_required for test keys and never call the live company-data service.

PRIMARY ENDPOINT

POST /v2/claims/verify

Send exactly one input form: a natural-language answer for supported-claim extraction, or a claims array when your system already has structured values.

{
  "company": {
    "name": "CompanyProof Sandbox Limited",
    "country": "GB",
    "registration_number": "CP000001"
  },
  "answer": "The company is active and was incorporated on 15 January 2020.",
  "monitor": false
}

{
  "company": {
    "name": "CompanyProof Sandbox Limited",
    "country": "GB"
  },
  "claims": [
    { "field": "status", "published": "Active" },
    { "field": "legal_form", "published": "Private limited company" }
  ],
  "monitor": false
}

For structured claims, send published. The legacy alias expected is also accepted. The complete JSON request is limited to 64 KiB.

DETERMINISTIC SCOPE

Six fields are currently guaranteed.

Officers, shareholders, group structures and financial claims are not yet part of this deterministic endpoint. Do not build production logic that assumes they are returned here.

RESPONSE MODEL

Evidence travels with every verdict.

The proof ID links the resolved company, individual claims, source context, decision events and future monitoring state. corrected means a supported field was found but its published value did not match the observed value.

{
  "proof_id": "prf_7dcf18e8a2f6c06a9a10d2c1",
  "company": {
    "id": "sandbox_company_001",
    "name": "COMPANYPROOF SANDBOX LIMITED",
    "registration_number": "CP000001",
    "country": "GB"
  },
  "claims": [
    {
      "claim_id": "clm_f3df4360de139d4f9d323779",
      "field": "status",
      "published": "Active",
      "observed": "Active",
      "verdict": "verified",
      "explanation": "The published value matches the sample company record.",
      "evidence": {
        "source_name": "CompanyProof Sandbox",
        "source_url": "https://companyproof.ai/docs#environments",
        "source_record_id": "sandbox_company_001",
        "retrieved_at": "2026-08-29T10:42:11.000Z"
      }
    },
    {
      "claim_id": "clm_15c1c8ae33b2520c5c9a9701",
      "field": "incorporation_date",
      "published": "2021-01-15",
      "observed": "2020-01-15",
      "verdict": "corrected",
      "explanation": "The published value conflicts with the sample company record.",
      "evidence": {
        "source_name": "CompanyProof Sandbox",
        "source_url": "https://companyproof.ai/docs#environments",
        "source_record_id": "sandbox_company_001",
        "retrieved_at": "2026-08-29T10:42:11.000Z"
      }
    }
  ],
  "summary": {
    "verified": 1,
    "corrected": 1,
    "stale": 0,
    "unsupported": 0
  },
  "monitoring": "off",
  "latency_ms": 0
}

SAFE RETRIES

One logical verification, one proof.

Send an Idempotency-Key on every write. Keys must contain 8–128 characters from A–Z a–z 0–9 . _ : - and are scoped to your account.

1. 01
   First request

   The proof is created, claim credits are consumed and the response is 201.

2. 02
   Same key, same request

   The stored proof is returned with 200 and Idempotent-Replayed: true. No additional credits are consumed.

3. 03
   Same key, changed request

   The request is rejected with 409 idempotency_conflict.

RATE AND USAGE LIMITS

Predictable monthly allowances. No automatic overage.

Each claim in a verification consumes one claim credit. Each monitored claim recheck consumes one more. Search, profile retrieval and adaptive intelligence are rate-limited but do not consume verification claim credits during the current beta. Requests stop at the relevant limit; CompanyProof does not create automatic overage charges.

CompanyProof REST 429 responses include Retry-After. The per-minute counter is shared by REST requests and MCP tool calls made with the same key; MCP tool failures are returned inside result.isError. Protocol discovery and tool listing do not consume the tool-call counter. Monitoring that reaches the monthly allowance pauses until the next UTC reset.

CONTINUOUS PROOF

Verified now. Watched afterwards.

With monitor: true, CompanyProof schedules only claims whose initial verdict is verified. The current beta check interval is approximately 24 hours; registry availability and source-refresh timing vary by jurisdiction.

1. 01
   Evidence recorded

   The published and observed values, source record and retrieval time enter the ledger.

2. 02
   Claim rechecked

   A successful unchanged check produces a ledger event and schedules the next check.

3. 03
   Difference detected

   The claim becomes stale, further checks stop for that claim and a signed webhook is queued.

Monitoring records can currently be reviewed in the CompanyProof account console. Public list, pause, resume and delete endpoints are not part of /v2; do not infer them from the dashboard.

WEBHOOKS · CLAIM.STALE

Authenticate every event before acting.

Create up to 10 active HTTPS endpoints in the account console. CompanyProof stores each endpoint secret encrypted, displays the secret once, rejects redirects and treats any 2xx response as successful delivery.

{
  "id": "evt_0c1d2e3f4a5b6c7d8e9f1011",
  "event": "claim.stale",
  "type": "claim.stale",
  "created_at": "2026-10-14T11:06:02.000Z",
  "data": {
    "proof_id": "prf_7dcf18e8a2f6c06a9a10d2c1",
    "claim_id": "clm_f3df4360de139d4f9d323779",
    "company": {
      "id": "sandbox_company_001",
      "name": "COMPANYPROOF SANDBOX LIMITED",
      "registration_number": "CP000001",
      "country": "GB"
    },
    "field": "status",
    "published_value": "Active",
    "verified_value": "Active",
    "previous_value": "Active",
    "current_value": "Dissolved",
    "verified_at": "2026-08-29T10:42:11.000Z",
    "changed_at": "2026-10-14T11:06:01.000Z",
    "source": {
      "sourceName": "CompanyProof Sandbox",
      "sourceUrl": "https://companyproof.ai/docs#environments",
      "retrievedAt": "2026-10-14T11:05:58.000Z",
      "recordId": "sandbox_company_001"
    }
  }
}

import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyCompanyProofWebhook(rawBody, header, secret) {
  const values = Object.fromEntries(
    header.split(",").map(part => part.split("=", 2))
  );
  const timestamp = Number(values.t);
  const supplied = Buffer.from(values.v1 || "", "hex");

  if (!Number.isFinite(timestamp)) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > 300) return false;

  const signed = Buffer.concat([
    Buffer.from(String(timestamp) + ".", "utf8"),
    rawBody
  ]);
  const expected = createHmac("sha256", secret).update(signed).digest();

  return supplied.length === expected.length &&
    timingSafeEqual(supplied, expected);
}

Delivery times out after 10 seconds. CompanyProof makes up to five attempts: immediately, then after roughly 1 minute, 5 minutes, 30 minutes and 2 hours. Delivery order is not guaranteed; deduplicate with CompanyProof-Event-Id and order business events with created_at. There is no public replay endpoint in this version. Return 2xx only after the event is durably accepted.

VERSIONING · LAST UPDATED 29 AUGUST 2026

Pin the major contract; tolerate additive fields.

The REST major version is part of the path: /v2. CompanyProof may add optional response fields, new error codes and new MCP tools without changing that version. Removing or renaming a field, changing its type, or making an optional request field required will use a new major path or a documented migration window.

ERROR MODEL

Machine-readable failures.

Errors use { "error": { "code": "…", "message": "…" } }. Branch on error.code; the human-readable message may become clearer without a version change.