> ## Documentation Index
> Fetch the complete documentation index at: https://docs.antei.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Validate Tax ID (Sandbox)

> Simulate tax ID validation against official tax authority registries.

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.

<Expandable title="Valid Tax ID – Sandbox">
  | Country | Tax ID            | Simulated Outcome    |
  | :------ | :---------------- | :------------------- |
  | DE      | `DE123456789`     | Valid, name matches  |
  | IN      | `29ABCDE1234F1Z5` | Valid, name mismatch |
  | US      | `123-45-6789`     | Invalid ID           |
</Expandable>

***

### Request Parameters

Provide the following fields to simulate a validation request:

<Accordion title="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.
</Accordion>

***

### Response Fields

The response includes full registry metadata for the provided tax ID:

<Accordion title="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.
</Accordion>

***

### Notes

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

***

### 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


## OpenAPI

````yaml api-reference/openapi_sandbox.json post /v1/tax/id-validate
openapi: 3.0.1
info:
  title: Antei Sandbox API
  description: >-
    Test and simulate integrations using Antei's sandbox environment. This is a
    sandbox-specific version exposing only limited endpoints for safe testing.
  version: 1.0.0
  license:
    name: MIT
  contact:
    name: Antei Developer Support
    email: support@antei.com
    url: https://antei.com
  x-sandbox: true
servers:
  - url: https://sandbox.antei.com
security:
  - bearerAuth: []
tags:
  - name: Tax Rate
    description: Calculate applicable tax rates based on product and customer details.
  - name: Tax ID Validation
    description: Validate tax identification numbers for compliance checks.
  - name: Taxation
    description: Unified tax calculation and validation workflows.
paths:
  /v1/tax/id-validate:
    post:
      tags:
        - Tax ID Validation
      summary: Validate a Tax ID
      description: >-
        Validates the provided tax identification number (TIN) against known tax
        registries for a specific country and returns validation details.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        description: Details required for Tax ID validation
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxIdValidationRequest'
      responses:
        '200':
          description: Validation result returned successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxIdValidationResponse'
        '400':
          description: Invalid input or malformed request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      description: >-
        Optional. Unique key to ensure idempotent operations (e.g., retry-safe
        requests).
      required: false
      schema:
        type: string
  schemas:
    TaxIdValidationRequest:
      type: object
      required:
        - tax_id
        - country
      properties:
        tax_id:
          type: string
          description: The tax identification number to validate
        customer_name:
          type: string
          description: Optional customer name for matching against registry
        country:
          type: string
          description: >-
            The country where the tax ID should be validated (ISO 3166-1
            alpha-2)
        state:
          type: string
          description: State or region code, if applicable
        county:
          type: string
          description: County or district, optional
        postal_code:
          type: string
          description: Postal or ZIP code, optional
        ip_address:
          type: string
          description: IP address of the customer (used for fallback geolocation)
      example:
        tax_id: US123456789
        country: US
        customer_name: Acme Inc.
        ip_address: 192.168.1.1
    TaxIdValidationResponse:
      type: object
      properties:
        valid:
          type: boolean
          description: Indicates whether the Tax ID is valid
        customer_name:
          type: string
          description: Customer name from the tax registry (if available)
        customer_name_match:
          type: boolean
          description: True if the provided name matches the registry name
        customer_type:
          type: string
          description: >-
            Type of the customer entity (e.g., BUSINESS, INDIVIDUAL, NONPROFIT,
            GOV)
        country:
          type: string
          description: Country associated with the tax ID
        state:
          type: string
          description: State/province/region from registry (if available)
        address:
          type: string
          description: Full address from registry (if available)
        source:
          type: string
          description: Registry source used (e.g., VIES, GSTIN, etc.)
        validation_timestamp:
          type: string
          format: date-time
          description: Timestamp of the validation attempt
        request_id:
          type: string
          description: Internal reference ID for this validation request
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````