Skip to main content
POST
/
v1
/
tax
/
id-validate
Validate a Tax ID
curl --request POST \
  --url https://sandbox.antei.com/v1/tax/id-validate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "tax_id": "US123456789",
  "country": "US",
  "customer_name": "Acme Inc.",
  "ip_address": "192.168.1.1"
}
'
{
  "valid": true,
  "customer_name": "<string>",
  "customer_name_match": true,
  "customer_type": "<string>",
  "country": "<string>",
  "state": "<string>",
  "address": "<string>",
  "source": "<string>",
  "validation_timestamp": "2023-11-07T05:31:56Z",
  "request_id": "<string>"
}
Use this endpoint in the Sandbox environment to simulate validation of a Tax Identification Number (TIN) against government registries. This helps test compliance logic, customer verification steps, and onboarding flows without calling real tax databases.

​
Valid Tax ID Scenarios

The Sandbox supports only the specific Tax IDs below for deterministic responses. Any other values will return empty or generic results.

​
Request Parameters

Provide the following fields to simulate a validation request:
  • tax_id: (string, required) – The customer’s Tax Identification Number.
  • customer_name: (string, optional) – Customer’s legal name (used to check name match).
  • country: (string, required) – ISO 3166-1 alpha-2 country code (e.g., US, DE, IN).
  • state: (string, optional) – State or region (useful for country-specific registries).
  • county: (string, optional) – County or district.
  • postal_code: (string, optional) – ZIP/postal code (used for location validation).
  • ip_address: (string, optional) – IP for fallback geolocation.

​
Response Fields

The response includes full registry metadata for the provided tax ID:
  • valid: (boolean) – Whether the tax ID is valid.
  • customer_name: (string) – Name retrieved from registry.
  • customer_name_match: (boolean) – Whether provided name matches registry record.
  • customer_type: (string) – Inferred customer classification:
    • B2C, B2B, PRISCH, PRIEDUI, GOV, PUBSCH, PUBEDU, PRIHOS, PUBHOS, NGO
  • country: (string) – Country returned from the registry.
  • state: (string) – Validated state or region.
  • address: (string) – Registered address (if available).
  • source: (string) – Validation source, e.g., VIES, GSTN.
  • validation_timestamp: (string) – ISO timestamp of when validation occurred.
  • request_id: (string) – Internal trace ID for support and logging.

​
Notes

Only the specified test IDs listed above work in the Sandbox. All other values return limited or placeholder responses.
The customer_name field is optional, but providing it allows you to simulate name match or mismatch behavior.
This endpoint does not make live registry calls in the Sandbox environment.
Use during onboarding, KYC, or compliance testing when working with tax-registered entities.

​
Usage Tips

Use this endpoint to simulate:
  • Validation of B2B or institutional tax registrations
  • Name mismatch handling logic
  • Country-specific registry behavior across EU, India, US, etc.
  • Auditable validation logs for test environments

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
Idempotency-Key
string

Optional. Unique key to ensure idempotent operations (e.g., retry-safe requests).

Body

application/json

Details required for Tax ID validation

​
tax_id
string
required

The tax identification number to validate

​
country
string
required

The country where the tax ID should be validated (ISO 3166-1 alpha-2)

​
customer_name
string

Optional customer name for matching against registry

​
state
string

State or region code, if applicable

​
county
string

County or district, optional

​
postal_code
string

Postal or ZIP code, optional

​
ip_address
string

IP address of the customer (used for fallback geolocation)

Response

Validation result returned successfully

​
valid
boolean

Indicates whether the Tax ID is valid

​
customer_name
string

Customer name from the tax registry (if available)

​
customer_name_match
boolean

True if the provided name matches the registry name

​
customer_type
string

Type of the customer entity (e.g., BUSINESS, INDIVIDUAL, NONPROFIT, GOV)

​
country
string

Country associated with the tax ID

​
state
string

State/province/region from registry (if available)

​
address
string

Full address from registry (if available)

​
source
string

Registry source used (e.g., VIES, GSTIN, etc.)

​
validation_timestamp
string<date-time>

Timestamp of the validation attempt

​
request_id
string

Internal reference ID for this validation request