VAT Checker API

The VAT Checker API lets you validate identifiers, run batches, manage recurring schedules, and fetch results from your own systems.

Base path: https://api.trustcomponent.com/taxvalidation/v1 Auth: Authorization: Bearer ak_… (a Project API key)

Common error responses on all endpoints: 401 (missing key), 403 (invalid key), and 402 when the Project is locked or its monthly validation quota is exhausted.

Validate a single VAT ID

curl -X POST "https://api.trustcomponent.com/taxvalidation/v1/validations" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ak_your_key_here" \
     -d '{
       "countryCode": "DE",
       "rawValue": "DE123456789",
       "companyName": "Example GmbH"
     }'

Field	Required	Description
`countryCode`	Yes	2-letter ISO country code — determines the ID scheme
`rawValue`	Yes	The VAT / business ID (spaces, dots, dashes, underscores are stripped; max. 20 characters after normalization)
`companyName`	No	Company name to match against the registry (max. 256 characters)
`address`	No	Address to match: `street`, `postalCode`, `city`, `region`, `countryCode`
`requesterVatId`	No	Your own VAT ID — enables BZSt qualified confirmation for German requesters
`customerMetadata`	No	Up to 20 key/value pairs (keys 1–64 chars, `a-z0-9_-`; values ≤ 512 chars), stored with the result
`preferredProvider`	No	Pin a registry: `VIES`, `BZST`, `HMRC`, `SWISS_UID`, `BRREG`, `ABR`, `NZBN`
`idempotencyKey`	No	A retried request with the same key isn’t processed twice
`correlationId`	No	Your own tracing ID, echoed back
`attachSchedule`	No	Also create a recurring schedule for this ID: `{ "frequency": "MONTHLY" }` plus optional `mode`, `preferredProvider`, `manualReviewOnAutomaticFailure`, `isEnabled`

API validations always run in automatic mode (they can still end up in manual review on failure, per your settings).

Responses:

Code	Meaning
`201`	Check completed synchronously — the response contains the full result
`202`	Processing asynchronously (`status: PENDING`) — fetch the result later or receive it by webhook
`200`	Idempotent replay — a request with this `idempotencyKey` was already processed
`422`	Invalid input (malformed country code, value too long, bad metadata, …)

{
  "validationRequestId": "…",
  "validationResultId": "…",
  "taxIdentifierId": "…",
  "status": "COMPLETED",
  "outcome": "VALID",
  "provider": "VIES",
  "providerStatus": "SUCCESS",
  "match": { "companyName": "MATCH", "address": "NOT_REQUESTED" },
  "responseData": { "companyName": "Example GmbH", "sourceReference": "…" },
  "checkedAt": "2026-07-01T10:30:00Z"
}

Outcome is one of VALID, INVALID, UNKNOWN, SOURCE_UNAVAILABLE, NOT_SUPPORTED — see Reading the outcome.

Validate a batch

curl -X POST "https://api.trustcomponent.com/taxvalidation/v1/validations/batch" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ak_your_key_here" \
     -d '{ "items": [ { "countryCode": "DE", "rawValue": "DE123456789" }, { "countryCode": "GB", "rawValue": "GB123456789" } ] }'

Each item uses the same shape as a single validation. Batches are always asynchronous: the response is 202 with one entry per item in input order (each PENDING, with its validationRequestId). Collect results by webhook or by fetching them. All items are validated up front — if any item is structurally invalid, the whole batch is rejected with 422 and nothing is processed.

Create a schedule

curl -X POST "https://api.trustcomponent.com/taxvalidation/v1/schedules" \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer ak_your_key_here" \
     -d '{ "countryCode": "DE", "rawValue": "DE123456789", "frequency": "MONTHLY" }'

Required: countryCode, rawValue, frequency (MONTHLY / QUARTERLY / YEARLY). Optional: mode, preferredProvider, manualReviewOnAutomaticFailure (default true), isEnabled (default true), plus the same matching fields as a single validation. Returns 201 with the scheduleId and nextRunAt. Requires the scheduled-validation plan feature (402 otherwise).

Delete a schedule

curl -X DELETE "https://api.trustcomponent.com/taxvalidation/v1/schedules/{scheduleId}" \
     -H "Authorization: Bearer ak_your_key_here"

Returns 204. Errors: 401, 403, 404.

Fetch a result

curl -X GET "https://api.trustcomponent.com/taxvalidation/v1/validation-results/{validationResultId}" \
     -H "Authorization: Bearer ak_your_key_here"

Returns 200 with the full result — input echo, outcome, provider, providerStatus, verificationMethod (AUTOMATIC / MANUAL), per-field match, responseData, and timestamps. Errors: 401, 403, 404.

Webhook events

Configure webhook endpoints per Project under Projects & Services. The VAT Checker emits:

Event type	Fired when
`taxvalidation.validation.completed`	Any check completes (automatic, manual review, or recorded)
`taxvalidation.validation.invalid`	Additionally, when the outcome is `INVALID`
`taxvalidation.validation.manual-review-required`	A check enters the Manual Review Queue

{
  "eventType": "taxvalidation.validation.completed",
  "occurredAt": "2026-07-01T10:30:02Z",
  "taxValidatorId": "…",
  "validationResultId": "…",
  "outcome": "VALID",
  "provider": "VIES",
  "providerStatus": "SUCCESS"
}

The manual-review-required payload carries the validationRequestId and its status instead of a result.