Integrated Vertex Validator automates business tax identification number validation during the tax determination in Vertex O Series Cloud. Enable the service to automatically validate tax numbers during tax determination.

If the service validates a tax number, the service includes it in the tax calculation and applies the appropriate business-to-business (B2B) tax treatment. If the service determines that the tax number is invalid, it excludes it and applies the appropriate business-to-consumer (B2C) tax treatment.

The service uses the Calculate Tax as a Seller request in the O Series Cloud REST API. You add the required validation fields described here to this request.

You can access the service from the Vertex O Series Cloud portal by clicking the Vertex Validator tile or by clicking the application selector on the ribbon to click the Vertex Validator button in the dropdown list.

Prerequisites

Ensure that you meet the following requirements:

You must use Vertex O Series Cloud with the O Series Cloud REST API.
You must have an active account and a valid license for Vertex O Series Cloud and Vertex Validator.
You must complete the onboarding process.
You need to review the Calculate Tax as a Seller request.

API authentication

Use one of the following credentials:

Validator Test—For the sandbox environment.
Validator—For the production environment.

Obtain a credential as described in Authentication and Access. Include the credential in your standard O Series Cloud authentication setup. For more information, see Authenticate O Series Cloud.

API integration

Use the following base URLs:

Environment	URL
Sandbox	`https://oseries-plus-api.sandbox.marketplace.taxamo.com`
Production	`https://oseries-plus-api.marketplace.taxamo.com`

Include tax calculation and tax number validation data in the Calculate Tax as a Seller request. Use the requests described in the Reference Guide.

Download OAS files

Download the Open API Specification (OAS) files in JSON format from the O Series Cloud REST API Reference.

Requests

Use the following request:

Request (Endpoint)	Description
Calculate Tax as a Seller (`/v2/supplies`)	This request represents a tax calculation from the seller's perspective.

🚧
Caution:
The service supports the QUOTATION and INVOICE message types. It doesn't support other message types.

The request includes the following fields:

Field	Description
`customer.taxRegistrations.taxRegistrationNumber`	The tax number to validate. If the value includes a country prefix (for example, `IE12345`) and `isoCountryCode` is missing or invalid, the service uses the prefix to determine the country.
`customer.taxRegistrations.taxRegistrationAdditionalId`	An additional tax number for specific countries.
`customer.taxRegistrations.isoCountryCode`	The country code for the tax registration. Some countries require this as a prefix in the tax number.
`customer.taxRegistrations.taxRegistrationType`	The tax scheme (for example, `VAT`). If you specify a value, use `VAT Registration`. If omitted, the service still performs validation. Vertex can also configure this field in the background during onboarding.
`validationResult.isValid`	A Boolean that lets you skip validation.

Responses

The service returns validation results in the following fields:

Field	Description
`isValid`	Indicates whether the tax number is valid. The service typically sets this value, but you can also provide it in the request.
`isSyntaxValid`	Indicates whether the tax number format is valid.
`validationInfo`	Provides additional data about the validation process.
`taxRegistrationNumberNormalized`	The tax number in a standardized format.
`cached`	Indicates whether the service used a cached validation result.
`cacheTimestamp`	The time the service sent the original validation request to the external service (if cached).
`name`	The business name associated with the tax number, if available from the tax authority.
`taxNumberService`	The validation service used (for example, `VIES`).
`freeformAddress`	The address associated with the tax number, if available from the tax authority.
`customer.customerCode.isBusinessIndicator`	Indicates whether the customer is a business. Set to `TRUE` when the tax number is valid.

Message processing

When you send a request, the service validates the tax number in the customer.taxRegistrations.taxRegistrationNumber field.

If valid, the service includes the tax number in the request sent to O Series Cloud.
If the tax number is invalid, the service removes it before sending the Calculate Tax as a Seller request.

🚧
Caution:
The service validates only tax numbers provided in the API request. It doesn't validate tax numbers created in Vertex O Series Cloud.

For example:

"lineItems": [
  {
    "customer": {
    "customerName": "Swatch",
    "destination": {
    "country": "CH"
    },
    "taxRegistrations": [
    {
      "taxRegistrationNumber": "CHCHE-116.294.121",
      "taxRegistrationType": "VAT Registration"
      },
      {
      "taxRegistrationNumber": "GB473116503"
      }
      ]
    },

The API returns the following validation data. The following snippet shows an example response for a valid tax number.

{
  "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"
                            },

The following snippet shows how the response indicates that the customer is a business. The service adds this to the response after validating the tax number.

"customer": {
  "customerCode": {
    "isBusinessIndicator": true,
      "value": "orlen"

For more information, see Message Processing.

Examples

For more information, see Examples.

Integrate the service

To integrate the service, follow these steps:

Obtain an access token. See Authentication and Access.
Include the credential in your standard O Series Cloud authentication setup. See Authenticate O Series Cloud.
Review the prerequisites and the Calculate Tax as a Seller request.
Add the required fields to the request.
Send the request.
Review the validation results from the response.