Validate and mask Taxpayer Identification Number (TIN) from US and EU countries. A TIN may be an Employer Identification Number (EIN), an Individual Taxpayer Identification Number (ITIN) or a Social Security number (SSN).
Most of the functions default to US country as you can see in the documentation below. Also for US country, entityType is not required. When trying to validate EU TIN we need to set both paramenters country and entityType as TIN format varies from ech country and entity types.
For EU TIN validation, we first try to validate by using an online API provided by the European Commisision, if any error is received from this API (for example, if the API is down), then we run our internal validations instead.
Status
Installation
Install the package via npm:
npm install tin-validator --save
Usage
isValid(value)
This method validates if the given value is a valid Taxpayer Identification Number.
Arguments
value(*): The string value to validate.
options (object, optional):
country (string, optional): Country of document to validate (by default, US).
entityType (string, optional): Possible values: natural-person and legal-entity. By default: natural-person.
skipExternalValidations (boolean, optional): Only applicable for EU TIN. When set to true, it skips external API validation and uses only internal validation. This is useful for performance, offline scenarios, or testing. By default: false.
Returns
(boolean): Returns whether the input value is a valid TIN or not.
This method will help you protect this sensitive piece of information by obfuscating some digits.
Arguments
value(*): The value to mask.
options (object, optional):
country (string, optional): Country of document to mask (by default, US).
entityType (string, optional): Regulation entity type (by default, natural-person).
skipExternalValidations (boolean, optional): Only applicable for EU TIN. When set to true, it skips external API validation and uses only internal validation. This is useful for performance, offline scenarios, or testing. By default: false.
skipValidations (boolean, optional): Applicable for US and EU TIN. When set to true, it skips all kind of validations. This is useful when calling mask() after calling isValid(). By default: false.
Returns
(string): Returns the masked value by replacing value certain digits by 'X'.
Example
mask({});// Throws an Error.mask('9-0-0700000');// Throws an Error.mask('900-70-0000');// => XXX-XX-0000mask('900700000');// => XXXXX0000
sanitize(value)
This method will remove all non numeric characters from the value.
Arguments
value(*): The value to sanitize.
options (object, optional):
country (string, optional): Country of document to sanitize (by default, US).
entityType (string, optional): Regulation entity type (by default, natural-person).
Returns
(string): Returns the sanitized value containing only numeric characters.
This method will standardize TIN values. Validators may accept TIN values for specific countries with formatting variations (e.g. omitting prefixes of zeros). Users should invoke this method prior value masking and DB persistence, as it returns the official version of the TIN.
Arguments
value(*): The value to standardize.
options (object, optional):
country (string, optional): Country of document to standardize (by default, US).
entityType (string, optional): Regulation entity type (by default, natural-person).