TIN Validation API for Developers: Validate Tax IDs in Onboarding Forms

Implement Tax ID validation as a form workflow, not just an API call.

The useful pattern is to treat the TIN field like any other structured user input: collect enough context, validate on the server, and return an error message that maps to the exact field the user can fix.

1. Ask for the country first, using an ISO 3166-1 alpha-2 country code such as FR, DE, or US.
2. Load local TIN types for that country when your form needs a specific identifier type, such as an EIN for United States business tax accounts.
3. Send the submitted value to your backend. Do not call a paid API directly from browser JavaScript.
4. Call the TIN validation API from your server and map failed validation checks back to inline field copy.
5. Store the normalised value only after you decide the field is acceptable for your product flow.

Use a small server endpoint as the browser boundary.

The browser should call your application, and your application should call the TIN validation REST API. That keeps API credentials private and gives you one place for rate limits, logging, retries, and product-specific decisions.

// Browser to your own backend
await fetch("/onboarding/tax-id/validate", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    country: "US",
    tinTypeId: "us-ein",
    tin: "12345678"
  })
});

// Your backend to TIN Validate
const response = await fetch("https://tin-validate.com/api/v1/validate", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.TIN_VALIDATE_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    country: form.country,
    tinTypeId: form.tinTypeId,
    tin: form.tin
  })
});

const result = await response.json();

return {
  valid: result.isValid,
  normalisedValue: result.normalisedValue,
  fieldError: result.isValid ? null : firstFailedCheck(result)
};

Translate validation checks into useful inline errors.

A generic message like "invalid tax ID" forces the user to guess. A better field error tells them which rule failed and what they can change.

Examples of useful field messages

• Length: "This tax ID type expects a different number of digits."
• Characters: "This tax ID type only accepts digits. Remove letters and punctuation."
• Structure: "The value does not match the country-specific structure for the selected tax ID type."
• TIN type mismatch: "This value does not match the selected TIN type. Check whether the user meant another local identifier."

TIN validation is not taxpayer verification.

Structural validation checks whether a submitted value matches country-specific TIN rules. It does not confirm that a taxpayer, business, or government record exists, and it does not perform a live lookup against tax authority, company registry, or government identity databases.

Use TIN validation to improve form quality and catch obvious input errors early. If your workflow legally requires confirmation that the taxpayer exists or owns the identifier, handle that as a separate verification process.