Bulk Tax ID Validations

You can validate a batch of Tax IDs using the Bulk Validation feature.

To validate a lot of Tax IDs at once, you can use the Bulk Tax ID API and endpoints. These are facilitated by 2 requests:

  • Validate Tax IDs: Use this request to validate a large number of Tax IDs in a single request.
  • Poll Results: Use this request to retrieve the results of the processing. Returned results are assigned a request_id that can be used to identify the results and retrieve them in future requests.
  • Poll Last Seen Result: Use this request retrieve information about the validation processing status.

Restrictions

  • The services for some countries in VIES have regularly scheduled downtime. This can delay any bulk upload processing during these times. See here for details.

API Authentication

Authentication is explained in the API Authentication topic.

Process Flow

The following diagram shows the possible steps for this processing, using both requests:

Process flow for Bulk Tax ID validations

Process flow for Bulk Tax ID validations

The steps are as follows:

  1. User sends Validate Tax IDs request (including numbers to be validated):
{
  "items": [
    {"input": {"tax_number": "000000000", "country_code": "PL"}},
    {"input": {"tax_number": "111111111", "country_code": "GB"}},
    ...
  ]

  1. Vertex Validator returns the response
Request response
{
    "items": [
        {
            "id": "ANKpMhAXMAA="
        },
        {
            "id": "ANKpMhAYMAA="
        },
        ...
    ]
}
  1. User sends Poll Results request to retrieve results.
  2. Vertex Validator returns results and the generated id and request_id fields:
{
    "items": [
        {
            "status": "processed",
            "request_id": "ANKpMhAXMAA=",
            "id": "CMGpMhACMAA=",
            "output": {
                "buyer_tax_number_valid": false,
                "buyer_tax_number_format_valid": false,
                "buyer_tax_number_validation_info": "tax-number-syntax-invalid"
            }
        },
        {
            "status": "processed",
            "request_id": "ANKpMhAYMAA=",
            "id": "CMGpMhAFMAA=", 
            "output": {
                "buyer_tax_number_valid": false,
                "buyer_tax_number_format_valid": true,
                "buyer_tax_number_validation_info": "tax-number-invalid-according-to-external-service",
                "buyer_tax_number_normalized": "111111111",
                "buyer_tax_number_service_cache_used": true,
                "buyer_tax_number_service_cache_timestamp": "2025-08-20T15:07:34Z",
                "tax_number_service": "tax.service.gov.uk.api"
            }
        }
    ]

  1. User sends a Poll Last Seen Result request with CMGpMhACMAA specified as the last-seen-id query parameter.
  2. Vertex Validator returns results.
    "items": [
        {
            "status": "processed",
            "request_id": "ANKpMhAXMAA=",
            "id": "CMGpMhACMAA=",
            "output": {
                "buyer_tax_number_valid": false,
                "buyer_tax_number_format_valid": false,
                "buyer_tax_number_validation_info": "tax-number-syntax-invalid"
            }
        },
        {
            "status": "processed",
            "request_id": "ANKpMhAYMAA=",
            "id": "CMGpMhAFMAA=", 
            "output": {
                "buyer_tax_number_valid": false,
                "buyer_tax_number_format_valid": true,
                "buyer_tax_number_validation_info": "tax-number-invalid-according-to-external-service",
                "buyer_tax_number_normalized": "111111111",
                "buyer_tax_number_service_cache_used": true,
                "buyer_tax_number_service_cache_timestamp": "2025-08-20T15:07:34Z",
                "tax_number_service": "tax.service.gov.uk.api"
            }
        }
    ]