The validator cache temporarily stores responses to business tax identification number validation requests from the external tax authority. Cached validation data includes the validation status and, when available, the associated business name and address.

When the service receives a validation request for the same tax number within the configured cache expiry window, it can reuse the cached validation data instead of sending a new request to the external tax authority. The cache applies across all service users, regardless of which user originally initiated the validation request.

The service uses cached validation data only to support tax number validation, and is subject to automatic expiry.

Business benefits

The validator cache improves the stability and performance of tax number validation workflows:

• Reduced dependency on external validation services—The service reuses recent validation results, reducing repeated requests to the external tax authority.
• Improved reliability—The cache helps reduce validation failures caused by external outages, rate limits, or timeouts.
• Lower validation latency—When cached validation results are available, the service completes validations immediately without waiting for responses from the external tax authority.

Capabilities

This feature provides the following capabilities:

• Cache expiry configuration—Controls how long the service can reuse a cached validation result.
  • The service defines cache expiry in days.
  • The service reuses only cached results created within the configured expiry window.
  • You can configure cache expiry in:
    • Validator > Settings > All Regions > Full Validator Cache Expiry (days).
    • Validator > Settings > selected region > Full Validator Cache Expiry (days).
  • If both settings exist, the region-level configuration overrides the global configuration.
• Cache usage indication—Identifies when the service uses a cached validation result.
  • User interface—The interface displays Valid (cache) or Invalid (cache) when the service uses cached data.
  • API response—The validation response includes a field that indicates when the service uses cached data.

Considerations

Note the following considerations:

• Shared cache architecture—The service uses a single shared-cache database across all users. User-specific or isolated cache databases are not supported.
• Maximum cache retention—The service automatically removes all cached validation data after 30 days. Regardless of configuration, the service never uses cached results older than 30 days.
• Limited data scope and purpose—The service uses cached data only for tax number validation responses. It does not use cached data for analytics, enrichment, profiling, or any other purpose.
• No guarantee of current status—Cached results reflect the status from the external tax authority at the time of validation. Because external data can change, cached results do not guarantee current or real-time accuracy beyond the configured cache expiration period.
• Enabled by default—The service enables caching by default for all accounts. To force real-time validation, set the cache expiry value to 0 days. However, the service still enforces a minimum cache duration of 15 minutes to prevent repeated requests for the same tax number and to protect external validation services from excessive traffic.
• Storage data—The cache stores only the following data returned by the external validation service: tax number validity status, business name associated with the tax number (if available), and the business address associated with the tax number (if available).

Validator cache data flow

Here's what happens during validation (when the cache is set to 30 days):

1. The financial host system sends a Validate Tax Number request to the service.

https://{service_uri}/api/v3/tax_numbers/1234567890/validate&country_code=GB&business_name=Vertex&cache_expiry_timeout_days=30&on_error=proceed

2. The service checks the cache for validation results created in the previous 30 days.
3. If the cache doesn't contain the tax number, the service sends a validation request to the external tax authority system, when available, and returns the validation result.
4. The service returns the validation result in the Validate Tax Number response.

{
  "invoice_address": {
  "freeform_address": "",
  "country": "GB"
},
  "buyer_tax_number": "1234567890",
  "tax_deducted": true,
  "billing_country_code": "GB",
  "buyer_tax_number_format_valid": true,
  "warnings": null,
  "buyer_tax_number_valid": true,
  "buyer_tax_number_normalized": "1234567890",
  "buyer_name": "Vertex"
}

The following diagram illustrates this process.