Validate a Tax ID
Tax ID Validation
Validate Tax ID (Sandbox)
Simulate tax ID validation against official tax authority registries.
POST
Validate a Tax ID
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:Request Parameters
Request Parameters
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:Response Fields
Response Fields
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
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Optional. Unique key to ensure idempotent operations (e.g., retry-safe requests).
Body
application/json
Details required for Tax ID validation
The body is of type object.
Response
200
application/json
Validation result returned successfully
The response is of type object.