Global TIN Validation

Overview

The Global TIN Validation API allows users to validate Taxpayer Identification Numbers (TINs) against the OECD specifications. This service verifies TIN numbers based on the provided country code and type (Individual or Entity).

Use Case

The Global TIN Validation API is designed for financial institutions, tax authorities, and businesses that need to validate TINs for compliance, reporting, or identity verification purposes. It ensures that TINs are correctly formatted and valid according to the respective country's standards.

API Details

API Request Body

curl --location 'https://api.signzy.app/api/v3/global/validate-tin' \
--header 'Authorization: <----Auth Token---->' \
--header 'Content-Type: application/json' \
--data-raw '{
    "tin": "770493581",
    "countryCode": "US",
    "tinType": "E"
}'

API Request Body Mapping

Parameter	Required/Optional	Data Type	Description
tin	Required	String	The Taxpayer Identification Number (TIN) to be validated. It should be formatted according to the specified country's standards. Example: "123-456/789"
countryCode	Required	String	The country code of the TIN, provided in either Alpha-2 or Alpha-3 format as per ISO 3166-1. Example: "US"
tinType	Required	String	The type of the TIN. Acceptable values are I for Individuals or E for Entities. Example: "E"

API Response Body

{
    "result": {
        "tinValid": true,
        "message": "The TIN is valid"
    }
}

API Response Body Mapping

Parameter	Required/Optional	Data Type	Description
tinValid	Required	Boolean	Indicates whether the TIN is valid (true or false).
message	Required	String	A descriptive message providing information about the validation result.

Message Mapping

Message	Description
"The TIN is valid"	The TIN passed all the available structure checks and is valid.
"Invalid request syntax, please check the documentation"	The API did not 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 entity type must be "I" for Individuals or "E" for Entities.
"The type of the TIN number must be either E for entities or I for individuals"	The TIN type can only be "I" for Individuals or "E" for Entities.
"Internal TIN validation error"	The API unexpectedly crashed.
"Error: Unsupported ISO3 country code"	The TIN validation for this ISO3 country code is not yet implemented.
"Error: Unsupported ISO2 country code"	The TIN validation for this ISO2 country code is not yet implemented.
"Error: Invalid ISO2 country code"	The country specified using an 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 TIN provided doesn't seem to be long enough to be valid.
"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"	The country doesn't have any equivalent of Tax Identification Numbers.
"No validation available for this type of entity for this country"	Validation for this entity type is not available for the specified country.
"Error: the TIN has invalid length for the specified country"	The length of the TIN 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 checksum test failed for the provided TIN/country pair.
"Error: the TIN's structure is invalid for the specified country"	The structure rules for the TIN failed for the provided TIN/country pair.
"Error: Unsupported checksum type"	Internal error that should never be seen by API users.

Sample Error

{
  "error": {
    "statusCode": 409,
    "name": "error",
    "message": "Error in getting data from upstream",
    "status": 409
  }
}

Error Response Parameters

Parameters	Description
error	This parameter contains the error.
error.name	the name of the error
error.message	the error message
error.status	status of the api
error.reason	Reason for error
error.type	Type of the error
error.statusCode	Request Status code from Signzy

Getting help

Please feel free to contact us if you have any questions, require clarification, or have ideas for how to make the documents or any of our services better.

You can reach out to us at [email protected]. We strive to provide prompt and reliable assistance, ensuring your queries are addressed effectively.

We value your feedback and are committed to making your experience smooth and enjoyable. Our team is dedicated to assisting you with any needs you may have. Thank you for choosing our services. We look forward to helping you!