TIN Format Validation

• POST /api/customers/{id}/identifications/v2 with a Person submission. See Create Customer Identification.
• PATCH /api/customers/{id}/identification-data, used to backfill a TIN on an existing customer. See Update Customer Identification Data.

​

Tax residence country

• On a Person submission, you can omit it only when identity.identity_country_code is US. The TIN is then checked against the US format.
• On PATCH /api/customers/{id}/identification-data, it’s always required with a TIN.

​

Formatting rules

• Whitespace is ignored. Spaces anywhere in the value, including between groups of digits, are removed before the check.
• Separators are accepted. Dashes (-), periods (.), and slashes (/) used between groups pass, so a US SSN like 123-45-6789 is accepted the same as 123456789.
• Finland is the exception. The century marker is part of the format, so 010101-123A passes and 0101011234 fails. See the table below.
• Letters are case-insensitive. Wherever a format allows a letter, upper and lower case both pass.

​

Country formats

​

Other countries

• Contain only letters, digits, +, and - (plus the whitespace and separators from Formatting rules)
• Include 4-20 digits. Letters and punctuation don’t count toward that total.

​

Errors

[
  {
    "code": "invalid_request",
    "message": "Tax identification number for country DE must match format: 12345678901",
    "docs_url": "https://docs.iron.xyz/errors#invalid_request",
    "beneficiary_index": null
  }
]

"Tax identification number for country DE must match format: 12345678901"

"Tax residence country is required when a tax identification number is provided"