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

Headers

​
Idempotency-Key
string

Body

application/json
​
tax_id
string
required
​
country
string
required
​
customer_name
string
​
state
string
​
county
string
​
postal_code
string
​
ip_address
string

Response

​
valid
boolean
​
customer_name
string
​
customer_name_match
boolean
​
customer_type
string
​
country
string
​
state
string
​
address
string
​
source
string
​
validation_timestamp
string<date-time>
​
request_id
string