Batch Tax ID Validation
If you have a list of tax ID numbers you would like to validate all at once, it is better to use our batch validation endpoint. Up to 1,000 tax IDs can be validated in a single request (limit of 10 on free trial accounts). This will be much faster than sending separate individual requests and will avoid triggering rate limiting. Batch requests are authenticated like any other request. Read our Authentication guide to learn how to authenticate your request.
Request
Batch validation requests are POST requests that include a JSON array of tax ID numbers and related details. Each object in the array must include a reference_id. The reference_id is your own internal identifier that will help you match the validations to the original request. It can be a number, uuid, email address, or any other unique identifier that works for your purposes.
Each object should also contain country (two-letter country code), tin (tax id number), and type (tax ID type, optional). Learn more about the object properties further down the page. Below is a request to validate four tax ID numbers. The third item is not valid, and the fourth item has an unsupported type for the United States.
POST https://v3.api.taxid.pro/validate
[
{
"reference_id": "1",
"country": "it",
"tin": "MRTMTT91D08F205J",
"type": "individual"
},
{
"reference_id": "2",
"country": "gb",
"tin": "2955839665",
"type": "individual"
},
{
"reference_id": "3",
"country": "za",
"tin": "912345678",
"type": "individual"
},
{
"reference_id": "4",
"country": "us",
"tin": "239874293",
"type": "vat"
}
]Response
The response body includes a JSON array with several properties that provide helpful information about the validation. The reference_id corresponds with the id you used in your original request. The is_valid property will be true when the tax id number is valid or false when it is invalid. In this example, the first two tax IDs were valid, but the third was not. The objects in the array are the same as the object in our standard API response, with the exception of an added reference_id property. Note that since the fourth item was an unsupported format, it includes an error_code.
HTTP/1.1 200 OK[
{
"reference_id": "1",
"is_valid": true,
"message": null,
"tin_compact": "MRTMTT91D08F205J",
"tin_standard": "MRTMTT91D08F205J",
"country_name": "Italy",
"format_name": "Codice Fiscale",
"error_code": null
},
{
"reference_id": "2",
"is_valid": true,
"message": null,
"tin_compact": "2955839665",
"tin_standard": "2955839665",
"country_name": "United Kingdom",
"format_name": "Unique Taxpayer Reference",
"error_code": null
},
{
"reference_id": "3",
"is_valid": false,
"message": "Input is too short.",
"tin_compact": null,
"tin_standard": null,
"country_name": "South Africa",
"format_name": null,
"error_code": null
},
{
"reference_id": "4",
"is_valid": false,
"message": null,
"tin_compact": null,
"tin_standard": null,
"country_name": null,
"format_name": null,
"error_code": "country_or_type_unsupported"
}
]Error Responses
If there is an issue with an individual item in the batch, such as an invalid country code or unsupported format type, the individual item will have an is_valid value of false and it will include an error_code that indicates what the issue is. The rest of the array items will still be returned with their validation results as in the example above.
HTTP/1.1 200 OK[
{
"reference_id": "4",
"is_valid": false,
"message": null,
"tin_compact": null,
"tin_standard": null,
"country_name": null,
"format_name": null,
"error_code": "country_or_type_unsupported"
}
]If there is a more pervasive issue, the response will come with an HTTP status code of 4XX or 5XX and any additional information will be included in the detail property.
HTTP/1.1 400 Bad Request{
"detail": "Invalid JSON object."
}Request Object Properties
Each property below should be included in an object in a JSON array.
reference_id string required
A unique identifier for each tax ID in the array. This can be a number, an email address, a UUID, or any other string that will help you identify the tax ID numbers in the validation response. While the order of the array is preserved from your original request, the reference_id serves as a safeguard to help you explicitly match tax ID numbers from your original request to the validation response.country string required
A two-letter country code, as defined in the ISO standard. If you need to use IRS country codes, see the is_irs query parameter below.tin string required
The tax ID Number. It may contain numbers, letters (uppercase or lowercase), dots, dashes, or slashes. Separators that are not standard for the tax ID format being tested will trigger an invalid response. For example, a U.S. EIN typically uses a dash after the first two digits. Valid input can include this dash, or no dash, and both versions will be valid. However, if if extra dashes are used, or dashes were put in the wrong place, or dots were used instead of dashes, the response will be invalid because the separators aren't appropriate for the format. Experiment with this on our home page.type string optional
This parameter is optional, but recommended. Specify individual, entity, or vat. Exclude this parameter to test all available types for a given country. Some caveats to keep in mind if you do not specify a type:
- The result will be valid if any format is valid.
- The result will only be invalid if all formats are invalid.
- Guidance provided in the message property may be less specific.
For example, there are three types of tax ID numbers in Germany, one for individuals, one for entities, and one for vat numbers. If your tax ID number is a valid Steuernummer, and you do not specify a type, the validator will test all three formats available, and the response will be valid: true because it was valid for one of the three types tested. We recommend experimenting with this setting to ensure you are getting the behavior you are expecting.