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:
Setting | Description |
---|---|
cache_expiry_timeout_days | Validation 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_error | Controls 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:
The steps are as follows:
- 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'
- The Tax ID is checked against the database for that country.
- The database returns a result.
- 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:
The steps are as follows:
- 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'
- 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).
- 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
Link | Description |
---|---|
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 Dashboard | You 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 Dashboard | You can log in here to retrieve your access token for the Sandbox environment. |
Updated 5 months ago