You can use this service to integrate the validation of Tax IDs such as VAT IDs with your existing Vertex O Series Cloud (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 an existing O Series Cloud request (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 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 business's 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 available on the Vertex Developer Network.
• You purchased Vertex Validator.
• You completed the onboarding process.
• Read the Calculate Tax as a Seller request topic from the Vertex O Series API documentation.

🚧

Caution

This service supports the QUOTATION and INVOICE Message Types only. The others are not supported.

Authentication

There are 2 different authentication tokens:

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

To authenticate your requests, open the O Series Cloud Dashboard (click the Vertex O Series tile) 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 Authenticate O Series Cloud topic in the O Series Cloud API documentation.

API overview

There are 2 different API URIs 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.

Open API Specification (OAS) file

The OAS file can be downloaded from the O Series Cloud API Reference tab.

Requests

You must use the Calculate Tax as a Seller request:

🚧

Caution

This service supports the QUOTATION and INVOICE Message Types only. The others are not supported.

The following fields are sent in the request:

Response

The following fields are returned in the response:

Features

The following features are available:

• Turning Off Validation
• Multiple Tax IDs and Registration Types
• Syntax-Only Check

Processing

When the request is sent, the service validates 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 and click the Vertex O Series (Cloud) tile. Choose the token.
2. Review the prerequisites and your existing O Series Cloud 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.

User interfaces (UIs)

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

The Vertex Validator UIs are described in the Vertex Validator UIs section that includes the following UIs and topics:

• Tax Number Validation Statistics UI
• Validations UI
• Vertex Validator Settings UI

Reports

You can use the Tax Number Validation report to retrieve validation information. To access this report, go to the UI and click Reports. More information is provided in the Tax Number Validation Report topic.

Useful links

In this section