Home / Use cases / Java

EU VAT validation in Java

Validate EU VAT numbers in Java using the built-in HttpClient (Java 11+) and Jackson for JSON deserialization. Works with Spring Boot, Quarkus, Micronaut, or any Java 11+ application.

Implementation steps

1. 1

   Use java.net.http.HttpClient — no extra HTTP library needed

   Create a shared HttpClient instance: HttpClient client = HttpClient.newBuilder().connectTimeout(Duration.ofSeconds(5)).build(). Make it a Spring @Bean or a static field — HttpClient is thread-safe and designed for reuse. Avoid creating a new HttpClient per request, which would bypass connection pooling and create unnecessary overhead under load.

2. 2

   Set the Authorization header with your API key from environment

   Build the request: HttpRequest request = HttpRequest.newBuilder().uri(URI.create("https://api.taxid.pro/v1/validate/" + country + "/" + vat)).header("Authorization", "Bearer " + apiKey).timeout(Duration.ofSeconds(10)).GET().build(). Load apiKey from System.getenv("TAXID_API_KEY") or, in Spring Boot, inject it with @Value("${taxid.api-key}") in the service constructor. Never hardcode the key.

3. 3

   Deserialize the JSON response with Jackson ObjectMapper

   Send the request synchronously with client.send(request, BodyHandlers.ofString()) and pass the response body to objectMapper.readValue(response.body(), VATResult.class). Configure ObjectMapper with DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES set to false so new fields added to the TaxID response in the future do not break deserialization. Throw a VATServiceException wrapping the HTTP status code for non-200 responses.

4. 4

   Return B2B validation status to your billing or checkout logic

   Return the VATResult record to your caller and branch on result.status(): for "active", set the customer's taxTreatment to REVERSE_CHARGE in your billing model; for "invalid", throw a VATValidationException that your controller maps to a 422 response with a user-facing message; for "service_unavailable", throw a VATServiceUnavailableException that maps to 503 so the caller can implement retry logic without coupling it to the service implementation.

Code example

import java.net.URI;
import java.net.http.*;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;

// Requires Java 11+ and jackson-databind
public class VATValidator {

  static final HttpClient client = HttpClient.newHttpClient();
  static final ObjectMapper mapper = new ObjectMapper();

  @SuppressWarnings("unchecked")
  public static Map<String, Object> validateVAT(
      String country, String vatNumber) throws Exception {

    var request = HttpRequest.newBuilder()
        .uri(URI.create("http://localhost:3000/api/v1/validate/" + country + "/" + vatNumber))
        .header("Authorization", "Bearer " + System.getenv("TAXID_API_KEY"))
        .GET()
        .build();

    var response = client.send(request, HttpResponse.BodyHandlers.ofString());
    return mapper.readValue(response.body(), Map.class);
  }

  public static void main(String[] args) throws Exception {
    var result = validateVAT("DE", "DE123456789");

    if (Boolean.TRUE.equals(result.get("valid"))) {
      System.out.println("Valid EU business: " + result.get("company_name"));
    } else if ("service_unavailable".equals(result.get("status"))) {
      System.out.println("VIES unavailable — retry later");
    } else {
      System.out.println("Invalid VAT number");
    }
  }
}

curl "http://localhost:3000/api/v1/validate/DE/DE123456789" \
  -H "Authorization: Bearer $TAXID_API_KEY"

# {
#   "valid": true,
#   "status": "active",
#   "company_name": "Example GmbH",
#   "company_address": "Musterstraße 1, 10115 Berlin",
#   "cached": false
# }

API response

The TaxID API returns a consistent JSON response for every validation request:

{
  "valid": true,
  "status": "active",
  "country_code": "DE",
  "vat_number": "123456789",
  "company_name": "Example GmbH",
  "company_address": "Musterstraße 1, 10115 Berlin",
  "request_date": "2026-05-10T00:00:00.000Z",
  "cached": false,
  "request_id": "req_01j..."
}

Error handling

The API uses a consistent Stripe-style error format. Always handle service_unavailable separately — VIES has occasional downtime and you should not reject valid customers during outages.

Related use cases