Input parameters

The following input parameters are available for the Validate Tax Number request:

Path parameters

The following field can be specified in the path:

Field	Details	Description
`tax_number`	Mandatory	The Tax ID or number that is to be checked.

Query parameters

The following fields can be specified in the URL of the request:

Field	Details	Description
`country_code`	Mandatory	The country where the Tax ID originates.
`country_subdivision_code`	Mandatory for Canada.	This is only required for Canada, where it is used to specify the Province such as Quebec.
`business_name`	Mandatory for Canada.	This is only required for Canada, where it is used to specify the name of the business who owns the Tax ID.
`cache_expiry_timeout_days`	Optional	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`	Optional	Controls how the service behaves when an external service returns an error. If you specify `proceed`, the Tax ID will be marked as invalid. If you specify `syntax_check`, the format of the ID is checked. If the Tax ID is valid, the following is returned: `tax-number-syntax-considered-valid-but-not-verified`

Output fields

The following fields are returned in the request's response:

Field	Description
`buyer_tax_number_normalized`	Returns a the ID in a standardized format.
`buyer_tax_number_valid`	Indicates whether the Tax ID is valid or not.
`buyer_tax_number_format_valid`	Indicates whether the syntax is valid.
`buyer_tax_number_validation_info`	Provides more detailed about the processing.
`name`	The name of the owner of the Tax ID. This is not returned for all countries.
`address`	The address of the owner of the Tax ID. This is only returned for some countries. This is not returned for all countries.
`buyer_tax_number_service_cache_timestamp`	If a cached value is returned, this field shows the time that the initial request was sent to the external service.
`buyer_tax_number_service_cache_used`	Indicates that the cache of Tax IDs was used to verify the number.

Validation information

The buyer_tax_number_validation_info can contain one of the following statuses:

Response	Description
`tax-number-country-blocked`	This county is blocked in the settings.
`tax-number-validation-not-available`	The service was not able to validate this number.
`tax-number-ignored`	The number is ignored because the settings have been changed to block numbers for this region, country or seller.
`tax-number-syntax-valid`	The syntax of the ID is valid. However, no further validations were done. In cases where a checksum is required, like for India, the ID is considered valid if the syntax is valid and the checksum is not configured.
`tax-number-syntax-invalid`	The syntax of the ID is invalid.
`tax-number-syntax-considered-valid-but-not-verified`	The syntax of the ID is valid. However, no further validations were done.
`tax-number-considered-valid-in-domestic-country`	The Tax ID is valid in the domestic country of the supplier.
`tax-number-valid-according-to-external-service`	The Tax ID has been validated against the Tax Authority's database of Tax IDs and is valid.
`tax-number-invalid-according-to-external-service`	The Tax ID has been validated against the Tax Authority's database of Tax IDs and is invalid.
`tax-number-validation-requested-additional-interactions`	The Tax Authority has requested additional parameters. For example, a country might require CAPTCHA validation and needs more information before they can validate the ID.
`tax-number-service-temporarily-unavailable`	Could not connect to validation service due to temporary unavailability of the service.
`tax-number-syntax-considered-valid-but-not-verified`	The Tax ID syntax is valid but the ID's status could not be verified by the external service. This occurs when the `on-error` settings is set to `syntax-check` and external service does not respond