Vertex Validator (Standalone)

Use Vertex Validator to verify Tax IDs.

Vertex Validator offers a real-time business-to-business (B2B) validation service that fits into your users’ workflows and helps fulfill several use cases. This service is especially valuable as the tax treatment can vary from the business-to-consumer (B2C) channel in many locations.

The service's API provides a way to manage your tax ID verification across multiple regions. This helps you to meet demanding and diverse requirements of various tax authorities.

📘

Note

This version is only available as standalone.

Features

The solution offers the following capabilities:

  • Support for more than 50 countries and regions. See Validation Type per Country.
  • Customers who may want to integrate supplier verification into their supplier onboarding process can also utilize this service.
  • You can use the service to verify their buyer’s business status before commencing a commercial relationship.

Restrictions

  • You cannot block countries.
  • Single Sign-On (SSO) is not supported in this version.
  • You must send 1 Tax ID per request. You cannot verify multiple IDs in a single request.

API Integration

To access the API, you need to retrieve your access token. See Accessing the API.

You can use the Validate VAT Number request to integrate.

Settings

The following settings are available and can be set in the request:

SettingDescription
cache_expiry_timeout_daysValidation results can be cached. This setting controls how recent the cached result that is returned is. For example, if it is set to 0, the service will validate the ID against the authority's database in real-time. If it is set to 30, the service will use results cached over the last 30 days.
on_errorControls how the service behaves when the external service returns an error due to unavailability or other reasons. If you specify proceed, the Tax ID will be marked as invalid. If you specify syntax_check, the syntax is checked, the ID is marked as valid (if correct) and the following is returned in the API response: buyer-tax_number-validation-info: "tax-number-syntax-considered-valid-but-not-verified".

Processing

You can use the Cache setting to vary whether the cache is checked or not. The following sections show examples for a real-time validation (where the cache is set to 0) and a cached validation (where the cache is set to 30 days).

Real-Time Validation

The following diagram shows a typical process flow where the cache is set to 0:

Standalone Validator Processing

Standalone Validator Processing - Cache = 0

The steps are as follows:

  1. A Validate VAT Number request is sent to the service. The details are specified in the URL:
https://{service_uri}/api/v3/tax_numbers/ABCD12345/validate&country_code=DE&business_name=Franc%27s%20Flowers&cache_expiry_timeout_days=0&on_error=proceed'
  1. The Tax ID is checked against the database for that country.
  2. The database returns a result.
  3. The result is returned in the Validate VAT Number response. For example:
{
"invoice_address": {
"freeform_address": "---",
"country": "DE"
},
"buyer_tax_number": "123456789",
"tax_deducted": true,
"billing_country_code": "DE",
"buyer_tax_number_format_valid": true,
"warnings": null,
"buyer_tax_number_valid": true,
"buyer_tax_number_normalized": "123456789",
"buyer_name": "---"
}

Cached Validation

The following diagram shows a typical process flow where the cache is set to 30 days:

Standalone Validator Processing

Standalone Validator Processing - 30 day cache

The steps are as follows:

  1. A Validate VAT Number request is sent to the service. The details are specified in the URL:
https://{service_uri}/api/v3/tax_numbers/ABCD12345/validate&country_code=DE&business_name=Franc%27s%20Flowers&cache_expiry_timeout_days=30&on_error=proceed'
  1. The service checks the last 30 days of entries in the cache. If the cache does not contain the Tax ID, then the Tax Authority's database is checked (where this available for the country).
  2. The result is returned in the Validate VAT Number response. For example:
{
"invoice_address": {
"freeform_address": "---",
"country": "DE"
},
"buyer_tax_number": "123456789",
"tax_deducted": true,
"billing_country_code": "DE",
"buyer_tax_number_format_valid": true,
"warnings": null,
"buyer_tax_number_valid": true,
"buyer_tax_number_normalized": "123456789",
"buyer_name": "---"
}

Messages

See Message Processing.

Useful Links

LinkDescription
Sandbox URI: https://tax-id-validator-api.sandbox.marketplace.taxamo.com//api/v3/The URI is the host for the API for the Sandbox environment.
Sandbox DashboardYou can log in here to retrieve your access token for the Sandbox environment.
Production URI: https://tax-id-validator-api.marketplace.taxamo.com//api/v3/The URI is the host for the API for the Production environment.
Production DashboardYou can log in here to retrieve your access token for the Sandbox environment.