Home / Use cases / .NET

EU VAT validation in .NET / C#

Validate EU VAT numbers in .NET 6+ and C# using HttpClient and System.Text.Json. Includes async/await pattern, strongly-typed response record, and IHttpClientFactory-ready setup.

Implementation steps

1. 1

   Register HttpClient via IHttpClientFactory in your DI container

   In Program.cs or Startup.cs, call builder.Services.AddHttpClient<VATValidationService>(client => { client.BaseAddress = new Uri("https://api.taxid.pro/"); client.Timeout = TimeSpan.FromSeconds(10); }). This registers a typed HttpClient that is injected into VATValidationService via constructor injection, follows ASP.NET Core's recommended lifetime management, and automatically rotates DNS to handle infrastructure changes at the TaxID API.

2. 2

   Set the Authorization header with your API key from IConfiguration

   In the VATValidationService constructor, set _httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", configuration["TaxID:ApiKey"]). Store the key in appsettings.json under TaxID:ApiKey and override it with an environment variable TAXID__APIKEY (double underscore for nested keys) in your deployment environment, keeping the key out of source control.

3. 3

   Deserialize the response with System.Text.Json into a C# record type

   Call var response = await _httpClient.GetAsync($"v1/validate/{country}/{vat}", cancellationToken) and check response.EnsureSuccessStatusCode(). Deserialize with var result = await response.Content.ReadFromJsonAsync<VATResult>(cancellationToken: cancellationToken). Configure JsonSerializerOptions with PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower (available in .NET 8) or use [JsonPropertyName("company_name")] attributes on the record properties to map snake_case API fields to PascalCase C# names.

4. 4

   Return the VATResult to your controller or application service

   Return the VATResult record from ValidateAsync and let the caller switch on result.Status: "active" triggers Stripe tax_exempt: 'reverse' or equivalent billing logic; "invalid" returns a ValidationProblem response from your API controller; "service_unavailable" throws a VIESUnavailableException that your global exception handler maps to HTTP 503, signalling to the client that it should retry rather than treating the number as definitively invalid.

Code example

using System.Net.Http.Headers;
using System.Text.Json;
using System.Text.Json.Serialization;

public record VATResult(
  [property: JsonPropertyName("valid")]           bool Valid,
  [property: JsonPropertyName("status")]          string Status,
  [property: JsonPropertyName("company_name")]    string? CompanyName,
  [property: JsonPropertyName("company_address")] string? CompanyAddress
);

// In your service — register HttpClient via IHttpClientFactory in prod
using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
  new AuthenticationHeaderValue("Bearer",
    Environment.GetEnvironmentVariable("TAXID_API_KEY"));

var url = $"http://localhost:3000/api/v1/validate/DE/DE123456789";
var json = await http.GetStringAsync(url);
var result = JsonSerializer.Deserialize<VATResult>(json)!;

if (result.Valid)
  Console.WriteLine($"Valid EU business: {result.CompanyName}");
else if (result.Status == "service_unavailable")
  Console.WriteLine("VIES unavailable — retry later");
else
  Console.WriteLine("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