REST API · VERSION 1

VATFind API.
Built to integrate.

Run checks, resolve company candidates, inspect country capabilities, schedule company-record monitoring, and track usage through one explicit VATFind contract.

const response = await fetch("https://vatfind.com/v1/checks", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.VATFIND_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID()
  },
  body: JSON.stringify({
    identifier_type: "vat_number",
    identifier: "GB123456789",
    country_code: "GB"
  })
});

const check = await response.json();
if (!response.ok) throw new Error(check.detail);
console.log(check.registry_match_status);

{
  "identifier_type": "vat_number",
  "identifier": "GB123456789",
  "country_code": "GB",
  "client_reference": "invoice-1048"
}

Agent quickstart · Markdown API reference · Supplier onboarding integration guide

Authentication and environments

Create and revoke keys in Dashboard → API & MCP. Send a key only in the HTTP Authorization header; never put it in a URL, browser bundle, or source repository. Both environments use one base URL; the key prefix selects deterministic sandbox or live processing.

Sandbox operations remain available without a paid subscription. Billable live operations require an active or trialling subscription, or the three-day grace period after a failed renewal. Existing prepaid balances remain usable only for workspaces that have not adopted the subscription. When paid access is unavailable, live billable endpoints return 402 with subscription_required or payment_required; read-only dashboard data and stored API resources remain available.

Authorization: Bearer vf_test_…
Content-Type: application/json

Checks

A check requires identifier_type, identifier, and an ISO alpha-2 country_code. Use tax_identifier only for a United States EIN; use vat_number for VAT-like identifiers outside the US. The optional company_name is compared with the matched legal name. client_reference and short string metadata are stored with the result.

Every create request must include an Idempotency-Key containing 8–128 URL-safe characters. Retrying the same body and key within 24 hours returns the original result without charging again; using the same key for a different body returns 409.

Company search

Provide country_code and at least one of name, registration_number, vat_number, or tax_identifier. Use tax_identifier only for a United States EIN; use vat_number outside the US, and never send both. VATFind returns up to 100 candidates and never silently chooses a fuzzy name result. If has_more is true, refine the query.

Company searches require an Idempotency-Key, just like checks. Company IDs begin cmp_, are scoped to the authenticated workspace and environment, and do not expose a source-system identifier. Company search is one billable unit in live and free in sandbox. Newly stored company snapshots share the environment's documented daily storage allowance and retention window; refreshing an existing company ID does not consume another storage slot.

The sources array describes the delivered record conservatively. Company records delivered by VATFind through licensed data services are labelled licensed_data_provider, even when the source-reported context names a public register, because optional identity, address, and contact sections can have different upstream lineage.

Country capabilities

The country endpoints distinguish VATFind format rules from company-record coverage. not_verified means VATFind has no verified country-level coverage guarantee for that dimension, so registry search and company-status retrieval are best-effort. It does not mean a country search is disabled. not_supported means VATFind does not offer that capability.

Company-record monitoring

The current company-monitoring API reruns the same identifier check against company-record sources on a daily, weekly, or monthly target cadence. It compares only the configured company fields with the last usable snapshot. Source outages do not overwrite the snapshot or create false company-change events.

Create, update, run, and archive operations require an Idempotency-Key. Reuse the same key and body for a retry within 24 hours. Required create fields are identifier_type, identifier, and country_code; cadence and watched_fields are optional. Supported cadences are daily, weekly, and monthly. Watched fields are registry_match_status, company_legal_status, legal_name, registration_number, vat_numbers, and registered_address.

curl https://vatfind.com/v1/monitors \
  -H "Authorization: Bearer vf_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: supplier-18429-monitor-v1" \
  -d '{
    "identifier_type": "vat_number",
    "identifier": "GB123456789",
    "country_code": "GB",
    "cadence": "daily",
    "client_reference": "supplier-18429",
    "webhook_url": "https://example.com/vatfind/events"
  }'

Completed monitor mutations durably bind their exact response to the Idempotency-Key for 24 hours, including the original baseline and any returned webhook signing secret.

Baseline creation and each successful scheduled or manual run use one live check; source failures do not. Daily, weekly, and monthly cadences are estimated at 30, 5, and 1 checks per monitor per month. Use monitoring:read to read monitors, monitoring:write to manage or run them, and monitoring:events to read the event feed.

Signed webhooks

Use a public HTTPS URL without embedded credentials; local, test, internal, localhost, and IP-literal destinations are rejected. VATFind returns the current signing secret whenever a non-null webhook_url is explicitly supplied, sends VATFind-Event-Id, VATFind-Timestamp, and VATFind-Signature, and retries failed or interrupted deliveries up to five attempts. Verify HMAC-SHA256 over timestamp.raw_body, reject stale timestamps, and deduplicate at-least-once delivery by the stable event ID.

Read the result correctly

VATFind intentionally does not return a single valid boolean. Syntax, registry association, tax-authority status, and legal-company status answer different questions.

Rate limits, retries, and errors

Live keys allow 60 requests per minute per key; sandbox keys allow 120. Workspace-level limits prevent multiplying source traffic across many keys. Per UTC day, a workspace can store up to 25,000 live or 2,000 sandbox checks and the same number of new company snapshots, create up to 1,000 live or 100 sandbox monitors, and run up to 25,000 live or 2,000 sandbox monitor refreshes. A monitor can be paused or resumed up to 20 times per UTC day; workspace status-change limits are 500 live or 100 sandbox transitions per day. Responses include X-Request-Id and successful authenticated responses include rate-limit headers.

Sandbox check, company-snapshot, and monitoring artifacts are retained for 90 days; live artifacts are retained for 730 days. VATFind keeps the baseline and latest checks referenced by a non-archived monitor while that monitor remains available.

Operation errors use application/problem+json with type, title, status, detail, code, request_id, and retryable. Retry only when retryable is true, honor Retry-After, and reuse the original idempotency key for any retried operation that requires one. Minute limits report the remaining seconds in the current minute; daily limits report the remaining seconds until 00:00 UTC. Unsupported methods return 405 with the endpoint's exact Allow header. A check-source outage is returned as a completed 201 result with registry_match_status: unavailable, a retryable warning, and zero credits used only after any live credit return is durably recorded.

Endpoint reference

GET /v1/usage reports completed usage events for supported operations by channel and operation. Its requests counters are a usage ledger, not a count of every HTTP transport attempt, rejected request, health check, or rate-limit probe.

The machine-readable contract is OpenAPI 3.1 and uses JSON Schema 2020-12. Treat additive response fields as non-breaking and pin your own generated client version.

Current tax-authority capability