API reference

Every operation with its request, response, and failure modes.

This reference is generated from the canonical OpenAPI 3.1 document that also produces the server's validation. Every field below is contract, not description.

Download openapi-v2.json

VAT validation

Validate a VAT registration with canonical evidence

POST/api/v2/validationsvat:validate

Returns the versioned public verification envelope, including authority scope, freshness, evidence and usage settlement.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Body · PublicVatValidationInput

Field	Type	Description
`countryCode`required	string	—`^[A-Za-z]{2}$`
`vatNumber`required	string	—`^[A-Za-z0-9 .+*-]+$`
`mode`	"sandbox" \| "live""sandbox" \| "live"default "sandbox"	—
`maxAgeSeconds`	integer	—
`allowStale`	boolean	—

Response

Statuses

200Saved VAT validation projected into the canonical public envelope
400Invalid request, freshness policy or source capability
401Missing or invalid authentication
403Organization, scope or environment access denied
409Idempotency conflict, unfinished or interrupted operation
410The saved result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Request rate or monthly allowance exceeded
500Unexpected internal error
503No successful save could be confirmed

Envelope · PublicVatValidationEnvelope

Field	Type	Description
`schemaVersion`required	PublicVerificationSchemaVersion	—
`operation`required	object	—
`subject`required	VatValidationOperationSubject	—
`result`required	VatValidationResult	—
`claims`required	VerificationClaim[]	—
`relationships`required	VerificationRelationship[]	—
`conflicts`required	VerificationConflict[]	—
`issues`required	VerificationIssue[]	—
`evidence`required	VerificationEvidence[]	—
`staleEvidence`required	VerificationEvidence[]	—
`freshness`required	VerificationFreshness	—
`usage`required	VerificationUsageSettlement	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/validations' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"countryCode":"DE","vatNumber":"123456789","mode":"sandbox"}'

Company identity

Search a certified company source

POST/api/v2/company-searchescompany:search

Returns sourced candidates with registry-qualified identities and an explicit resolution boundary.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Body · PublicCompanySearchInput

Field	Type	Description
`countryCode`required	string	—`^[A-Za-z]{2}$`
`query`required	string	—
`mode`	"sandbox" \| "live""sandbox" \| "live"default "sandbox"	—
`limit`	integerdefault 5	—
`maxAgeSeconds`	integer	—
`allowStale`	boolean	—

Response

Statuses

200Saved company search projected into the canonical public envelope
400Invalid request, freshness policy or source capability
401Missing or invalid authentication
403Organization, scope or environment access denied
409Idempotency conflict, unfinished or interrupted operation
410The saved result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Request rate or monthly allowance exceeded
500Unexpected internal error
503No successful save could be confirmed

Envelope · PublicCompanySearchEnvelope

Field	Type	Description
`schemaVersion`required	PublicVerificationSchemaVersion	—
`operation`required	object	—
`subject`required	CompanySearchOperationSubject	—
`result`required	CompanySearchResult	—
`claims`required	VerificationClaim[]	—
`relationships`required	VerificationRelationship[]	—
`conflicts`required	VerificationConflict[]	—
`issues`required	VerificationIssue[]	—
`evidence`required	VerificationEvidence[]	—
`staleEvidence`required	VerificationEvidence[]	—
`freshness`required	VerificationFreshness	—
`usage`required	VerificationUsageSettlement	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/company-searches' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"countryCode":"FR","query":"atelier exemple","mode":"sandbox","limit":5}'

Resolve a company and its VAT registration through reviewed fallbacks

POST/api/v2/company-resolutionscompany:search

Runs the jurisdiction plan through official sources, SERP discovery, reviewed retrieval and independent VAT validation. Locator results remain separate from claim evidence.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Body · PublicCompanyResolutionInputV2

Field	Type	Description
`countryCode`required	string	—`^[A-Za-z]{2}$`
`query`required	string	—
`mode`required	"live""live"	—
`limit`	integerdefault 5	—
`maxAgeSeconds`	integer	—
`allowStale`	boolean	—

Response

Statuses

200Saved company resolution with field evidence, source trail and VAT validation
400Invalid request, freshness policy or source capability
401Missing or invalid authentication
403Organization, scope or environment access denied
409Idempotency conflict, unfinished or interrupted operation
410The saved result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Request rate or monthly allowance exceeded
500Unexpected internal error
503No successful save could be confirmed

Envelope · PublicCompanyResolutionEnvelopeV2

Field	Type	Description
`schemaVersion`required	"2026-09-07""2026-09-07"	—
`operation`required	VerificationOperationReceipt	—
`subject`required	object	—
`result`required	CompanyResolutionResultV2	—
`usage`required	VerificationUsageSettlement	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/company-resolutions' \
  --header 'Authorization: Bearer vat_live_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"countryCode":"FR","query":"Atelier Exemple","mode":"live","limit":5}'

Verify a registry-qualified legal entity

POST/api/v2/company-verificationscompany:verify

Looks up one explicit jurisdiction, register and registry identifier, then returns source facts and claim comparisons separately.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Body · PublicCompanyVerificationInput

Field	Type	Description
`countryCode`required	string	—`^[A-Za-z]{2}$`
`register`required	string	—`^[A-Za-z0-9][A-Za-z0-9._:-]*$`
`registryId`required	string	—`^[A-Za-z0-9 .-]+$`
`mode`	"sandbox" \| "live""sandbox" \| "live"default "sandbox"	—
`claims`	objectdefault {}	—
`maxAgeSeconds`	integer	—
`allowStale`	boolean	—

Response

Statuses

200Saved company verification projected into the canonical public envelope
400Invalid request, freshness policy or source capability
401Missing or invalid authentication
403Organization, scope or environment access denied
409Idempotency conflict, unfinished or interrupted operation
410The saved result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Request rate or monthly allowance exceeded
500Unexpected internal error
503No successful save could be confirmed

Envelope · PublicCompanyVerificationEnvelope

Field	Type	Description
`schemaVersion`required	PublicVerificationSchemaVersion	—
`operation`required	object	—
`subject`required	CompanyOperationSubject	—
`result`required	CompanyVerificationResult	—
`claims`required	VerificationClaim[]	—
`relationships`required	VerificationRelationship[]	—
`conflicts`required	VerificationConflict[]	—
`issues`required	VerificationIssue[]	—
`evidence`required	VerificationEvidence[]	—
`staleEvidence`required	VerificationEvidence[]	—
`freshness`required	VerificationFreshness	—
`usage`required	VerificationUsageSettlement	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/company-verifications' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"countryCode":"FR","register":"sirene","registryId":"100000001","mode":"sandbox","claims":{"legalName":"ATELIER EXEMPLE SAS"}}'

VAT discovery

Discover sourced VAT associations for a legal entity

POST/api/v2/company-vat-discoveriesvat:discover

Verifies one registry-qualified entity, retains every sourced VAT association and reports an optional VAT authority check independently.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Body · PublicCompanyVatDiscoveryInput

Field	Type	Description
`countryCode`required	string	—`^[A-Za-z]{2}$`
`register`required	string	—`^[A-Za-z0-9][A-Za-z0-9._:-]*$`
`registryId`required	string	—`^[A-Za-z0-9 .-]+$`
`mode`	"sandbox" \| "live""sandbox" \| "live"default "sandbox"	—
`validateVat`	booleandefault true	—
`maxAgeSeconds`	integer	—
`allowStale`	boolean	—

Response

Statuses

200Saved VAT discovery projected into the canonical public envelope
400Invalid request, freshness policy or source capability
401Missing or invalid authentication
403Organization, scope or environment access denied
409Idempotency conflict, unfinished or interrupted operation
410The saved result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Request rate or monthly allowance exceeded
500Unexpected internal error
503No successful save could be confirmed

Envelope · PublicVatDiscoveryEnvelope

Field	Type	Description
`schemaVersion`required	PublicVerificationSchemaVersion	—
`operation`required	object	—
`subject`required	CompanyOperationSubject	—
`result`required	VatDiscoveryResult	—
`claims`required	VerificationClaim[]	—
`relationships`required	VerificationRelationship[]	—
`conflicts`required	VerificationConflict[]	—
`issues`required	VerificationIssue[]	—
`evidence`required	VerificationEvidence[]	—
`staleEvidence`required	VerificationEvidence[]	—
`freshness`required	VerificationFreshness	—
`usage`required	VerificationUsageSettlement	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/company-vat-discoveries' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"countryCode":"FR","register":"sirene","registryId":"100000001","mode":"sandbox","validateVat":true}'

Candidate selection

Persist an operator-selected company-search candidate

POST/api/v2/company-searches/{searchOperationId}/selectioncompany:search

Creates one immutable, organization- and environment-scoped selection event for an evidence-backed candidate in an existing completed company search or guided company resolution. Locator-only discovery leads must first be retrieved from an authority source. Requires company search permission.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Content-Type`required	string	application/json.
`Idempotency-Key`required	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Path parameters

Field	Type	Description
`searchOperationId`required	string	—

Body · CompanySearchCandidateSelectionInputV1

Field	Type	Description
`mode`required	VerificationEnvironment	—
`candidate`required	LegalEntityIdentity	—

Response

Statuses

200Existing immutable candidate selection
201New immutable candidate selection
400Invalid operation ID, idempotency key or strict request body
401Missing or invalid authentication
403Organization, permission or environment access denied
404Completed company search or selected candidate not found in this scope
409Idempotency conflict or this search already has a selection
410The company-search result expired or was source-suppressed
413Request body exceeds 4096 bytes
415JSON content type required
429Too many requests
500Unexpected internal error
503The company search or selection could not be confirmed

Envelope · CompanySearchCandidateSelectionResponseV1

Field	Type	Description
`schemaVersion`required	"2026-09-06""2026-09-06"	—
`id`required	string	—
`searchOperationId`required	string	—
`environment`required	VerificationEnvironment	—
`candidateRank`required	integer	—
`resolution`required	OperatorSelectedResolution	—
`replayed`required	boolean	—

Examples

curl --request POST \
  'https://vat.tools/api/v2/company-searches/9c2f5b64-1a3d-4e6f-8b7c-0d1e2f3a4b5c/selection' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: 8f0c1a52-4b6e-4f17-9d2a-3c5e7b9a1d40' \
  --data '{"mode":"sandbox","candidate":{"jurisdiction":"FR","register":"sirene","registryId":"100000001"}}'

Verification history

List canonical verification responses

GET/api/v2/verificationshistory:read

Returns immutable saved responses in stable newest-first order for one organization environment. Defaults to V1; explicit V2 admits only exact company verification under current retained-review policy. Evidence servedAt is refreshed for delivery. Unavailable retained V2 records are omitted; legacy runs are never reconstructed.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Query parameters

Field	Type	Description
`mode`	"sandbox" \| "live"	—
`schemaVersion`	"2026-09-01" \| "2026-09-07"	—
`kind`	"vat_validation" \| "company_search" \| "company_verification" \| "vat_discovery"	—
`limit`	integer	—
`cursor`	PublicVerificationHistoryCursorV1	—

Response

Statuses

200V1 or exact company-verification V2 history page
400Invalid query or cursor
401Missing or invalid authentication
403Organization, scope or environment access denied
429Too many requests
500Unexpected internal error
503History or a durable response snapshot is unavailable

Examples

curl --request GET \
  'https://vat.tools/api/v2/verifications?mode=mode_value&schemaVersion=schemaVersion_value&kind=kind_value&limit=25&cursor=cursor_value' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \

Get one canonical verification response

GET/api/v2/verifications/{operationId}history:read

Returns the original immutable saved response within the authenticated organization environment. Defaults to V1; explicit V2 admits only exact company verification under current retained-review policy. Evidence servedAt is refreshed for delivery.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Path parameters

Field	Type	Description
`operationId`required	string	—

Query parameters

Field	Type	Description
`mode`	"sandbox" \| "live"	—
`schemaVersion`	"2026-09-01" \| "2026-09-07"	—

Response

Statuses

200Original V1 or exact company-verification V2 snapshot
400Invalid operation identifier or environment
401Missing or invalid authentication
403Organization, scope or environment access denied
404No completed verification exists in this organization environment
410The saved result expired or was source-suppressed
429Too many requests
500Unexpected internal error
503History or the durable response snapshot is unavailable

Examples

curl --request GET \
  'https://vat.tools/api/v2/verifications/9c2f5b64-1a3d-4e6f-8b7c-0d1e2f3a4b5c?mode=mode_value&schemaVersion=schemaVersion_value' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \

Other

Download one retained company evidence record

GET/api/v2/verifications/{operationId}/company-evidence

Returns the complete permitted original snapshot in JSONL or CSV, including original source dates and historical usage. Delivery charges zero operation units and performs no source work; a live request consumes one shared incoming-request slot. Requires history:read. Current retention and exact source delivery policy are checked before any bytes are sent.

Request

Headers

Field	Type	Description
`Authorization`required	string	Bearer developer key bound to this environment.
`Idempotency-Key`	string	8–128 chars, [A-Za-z0-9][A-Za-z0-9._:-]*. Reuse it to recover the same logical operation.

Path parameters

Field	Type	Description
`operationId`required	string	—

Query parameters

Field	Type	Description
`mode`	"sandbox" \| "live"	—
`schemaVersion`required	"2026-09-01" \| "2026-09-07" \| "canonical-company-2026-09-30"	—
`format`required	"jsonl" \| "csv"	—

Response

Statuses

200One original saved company evidence record as an attachment
400Invalid path or query
401Authentication required
403Organization, environment or scope denied
404No completed saved response of this schema in this organization environment
409Selection required or profile/source export unavailable
410Saved evidence expired or was suppressed
429Incoming request limit reached
500Unexpected internal error
503Saved evidence, retention or request admission cannot be confirmed

Examples

curl --request GET \
  'https://vat.tools/api/v2/verifications/{operationId}/company-evidence?mode=mode_value&schemaVersion=schemaVersion_value&format=format_value' \
  --header 'Authorization: Bearer vat_sandbox_REPLACE_WITH_YOUR_KEY' \