OpenTIN Technical documentation

The OpenTIN API is available through three different interfaces. Select the one that matches the product you subscribed to.

Not sure which interface to choose? See the interface comparison table.

AWS Marketplace
OpenTIN API — API to verify the validity of Tax Identification Numbers
How to recognise it
  • Your AWS Marketplace subscription title does not contain the word (SaaS)
  • You call the API using the AWS SDK (boto3 / Amazon.DataExchange) via send_api_asset
  • No bearer token — authentication is handled by AWS Data Exchange
Go to Data Exchange documentation
AWS Marketplace
OpenTIN API (SaaS) — Verify the validity of Tax Identification Numbers
⚠ The title of this offer contains (SaaS) — this is the only difference visible on the AWS Marketplace listing page compared to the Data Exchange offer above.
How to recognise it
  • Your AWS Marketplace subscription title contains (SaaS)
  • You received a JWT bearer token after subscribing
  • Your endpoint is {region}.opentin-api.open-automation.io
Go to SaaS documentation
Azure Marketplace
OpenTIN API
How to recognise it
  • You subscribed through the Azure Marketplace
  • You received a JWT bearer token after subscribing
  • Your endpoint starts with azure.opentin-api.open-automation.io
Go to Azure documentation
API API responses explained
/tin_validate/{country}/{type}/{tin}

Response samples

  {
    "tin_valid": 0,
    "message": "string",
    "ctry_spec_ver": "string",
    "ctry_spec_chk_dt": "string"
  }
TIN Validation API

Download OpenAPI specification: Download

This API allows to validate a TIN number against OECD specifications



Validate TIN
PATH PARAMETERS
country
required
string
Example: USA
The country of the TIN number in either Alpha-2 or Alpha-3 format of the ISO 3166-1 specification
type
required
string
Example: I
The type of the TIN number. Only two values are accepted, I for Individuals or E for Entities
tin
required
string
Example: 123-456/789
The TIN number to validate
Responses
200 response
Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
tin_valid
integer
message
string
ctry_spec_ver
string
ctry_spec_chk_dt
string

-"Invalid request syntax, please check the documentation"
# The API didn't understand your request at all

- "The country code must be a valid ISO 3166-1 Alpha-2 OR Alpha-3 code"
# The country code must be 2 or 3 characters long and from the ISO 3166-1 standard

- "Error: the parameter 'entity_type' must be either I for individuals or E for entities"
- "The type of the TIN number must be either E for entities or I for individuals"
# The entity type can be only "I" for Individuals (physical persons) or "E" for Entities (Companies)

- "Internal TIN validation error"
# The API unexpedly crashed

- "Error: Unsupported ISO3 country code"
- "Error: Unsupported ISO2 country code"
# The TIN validation for this country is not yet implemented (contact our support if you encounter this rare case)

- "Error: Invalid ISO2 country code"
# The country you specified using a ISO2 code is not part of the 3166-1 standard

- "Error: the parameter 'tin' is mandatory"
# The TIN parameter was not found in the request

- "Error: the parameter 'entity_type' is mandatory"
# The "entity_type" parameter was not found in the request

- "Error: The TIN length is invalid"
# The number you provided doesn't seem to be long enough to be a valid TIN

- "This country is not a member of OECD"
# The provided country isn't participating in the OECD CRS initiative

- "This country does not use TINs"
# This country doesn't have any equivalent of Tax Identification Numbers

- "No validation available for this type of entity for this country"
# All implemented countries there is a validation available for Individuals
# For certain countries a validation for Entities is also available

- "Error: the TIN has invalid length for the specified country"
# The length of the TIN number is not valid for the specified country

- "Error: the TIN's format is invalid for the specified country"
# The format of the TIN doesn't follow the official specification for this country

- "Error: the TIN's checksum is invalid for the specified country"
# The vast majority of countries use complex checksum algorithms to ensure the TIN number is valid. This test failed for the provided TIN/country pair

- "Error: the TIN's structure is invalid for the specified country"
# The rules for the structure of the TIN failed for the provided TIN/country pair

- "Error: Unsupported checksum type"
# Internal error that should never be seen by the API users

- "The TIN is valid"
# The message that we want to see the most! The TIN passed all the available structure checks
↑
Сontact form