You can use this service to integrate the validation of Tax IDs such as VAT IDs with your existing Vertex O Series Cloud (known hereafter as O Series Cloud) deployment. You can validate the syntax and, where available, whether the Tax ID is active and considered valid by the validation provider, such as the VAT Information Exchange System (VIES).

This service uses your existing OSC requests, such the Calculate Tax as a Seller request from the O Series Cloud REST API, to integrate the service. You add the fields described here to this request.

You can access the dedicated UI for Vertex Validator by going to the O Series Cloud Dashboard here and clicking the Vertex Validator tile. This gives you access to settings and reports.

Business Benefits

This service helps you to do the following:

• Support for more than 50 countries and regions.
• Support for multiple validation types. For example, real-time and cache-based validations are supported.
• Dual number validation. For example, in Canada it can validate both GST and HST.
• Some sellers are required to validate a businesses’ tax number before applying a reverse charge and zero rating the transaction. Vertex’s B2B validation service supports this.
• Customers who may want to integrate supplier verification into their supplier onboarding process can also utilize this service.

Supported countries

The supported countries are listed in the Validation Type per Country topic.

Prerequisites

• You must have an existing O Series Cloud installation and use version 2 of the O Series Cloud API. The O Series Cloud API documentation is here on the Vertex Developer Network.
• You have purchased this service.
• You have completed the onboarding process.
• Read the Calculate Tax as a Seller request topic from the Vertex O Series API documentation.

Authentication

There are 2 different authentication tokens:

• Validator test: This token is used to access the Test system.
• Validator: This is used to access the Production system.

To authenticate your requests, open the O Series Cloud Dashboard (click the Vertex O Series tile here) and click the Security & Credentials tab. Select the Validator token. Use Validator for production and Validator Test for the sandbox:

You need to use this token as part of your regular O Series Cloud authentication setup. More information is provided in the In the Authenticate O Series Cloud topic in the O Series Cloud API documentation.

API overview

There are 2 different API URLs for sandbox and production systems:

You need to add the Tax ID and other information to the body of your Calculate Tax as a Seller request, using the API fields. Fields are listed in the Fields Reference topic.

Requests

You must use one of the Calculate Tax as a Seller request:

The following fields are sent in the request:

Response

The following fields are returned in the response:

Features

Switching validation provider

You can switch from the default validation service for countries that support these types of validations.

Turning off validation

You can turn off validation in the API request or you can set this per country in the UI-based Settings.

To do so using the API, ensure the customer.taxRegistrations.validationResult.isValid field is set to true in your requests:

customer.taxRegistrations.validationResult.isValid: true

Processing

If you call the O Series Cloud Plus endpoint, the service will validate the Tax ID (specified in the customer.taxRegistrations.taxRegistrationNumber field). If the Tax ID is valid, it is passed to O Series Cloud. If it is not valid, the Tax ID is removed before the Calculate Tax as a Seller request is sent to O Series Cloud.

🚧

Warning

This service only validates Tax IDs that are specified in the API field. Tax IDs that are created on the O Series Cloud UI are not validated.

For example:

<----Code omitted for clarity----->
    "lineItems": [
        {
            "customer": {
                "customerName": "Swatch",
                "destination": {
                    "country": "CH"
                },
                "taxRegistrations": [
                    {
                        "taxRegistrationNumber": "CHCHE-116.294.121",
                        "taxRegistrationType": "VAT Registration"
                    },
                    {
                        "taxRegistrationNumber": "GB473116503"
                    }
                ]
            },
<----Code omitted for clarity----->

The API returns the following validation information. This snippet shows an example result for a valid Tax ID:

{
    "data": {
        "documentDate": "2025-07-23",
        "lineItems": [
            {
                "customer": {
                    "customerName": "MWST-Gruppe, The Swatch Group SA",
                    "destination": {
                        "country": "CH",
                        "taxAreaId": "807560000"
                    },
                    "taxRegistrations": [
                        {
                            "isoCountryCode": "CH",
                            "taxRegistrationNumber": "CHCHE-116.294.121",
                            "taxRegistrationType": "VAT Registration",
                            "validationResult": {
                                "cacheTimestamp": "2025-07-23T09:35:34.4650Z",
                                "cached": true,
                                "isSyntaxValid": true,
                                "isValid": true,
                                "name": "MWST-Gruppe, The Swatch Group SA",
                                "taxNumberService": "uid.admin.ch",
                                "taxRegistrationNumberNormalized": "CHE116.294.121",
                                "validationInfo": "tax-number-valid-according-to-external-service"
                            },                         
<----Code omitted for clarity----->

The following snippet shows how the response indicates that the customer is a business. The service adds this to the response after the Tax ID is validated:

<----Code omitted for clarity----->
                "customer": {
                    "customerCode": {
                        "isBusinessIndicator": true,
                          "value": "orlen"
<----Code omitted for clarity----->

Integration steps

To integrate the service, complete the following steps:

1. Retrieve the API token. Log on to the O Series Cloud Dashboard here and click the Vertex O Series (Cloud) tile. Choose the token.
2. Review the prerequisites and your existing OSC API requests.
3. Add the following information to the body of the request:

4. Send the request.
5. Check that the following fields are in the response:

Examples

Examples are provided in the Examples topic.

Dashboards (UIs)

To access the UI, go to Vertex portal here and click the Vertex Validator tile.

You can access the following UIs:

• Tax Number Validations UI
• UI-based Settings
• Report

Reports

You can use the Tax Number Validation report to retrieve validation information.

To access this report go to the UI and click Reports

Useful links

In this section