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

> Validate a customer’s Tax Identification Number (TIN) and receive registry verification details.

Use this endpoint to validate a **Tax ID** against official tax authority records. This ensures regulatory compliance and helps verify customer authenticity before transactions.

***

## Request Parameters

The following fields can be included in the request:

<Accordion title="Request Parameters">
  * `tax_id` *(string, required)* – The customer’s Tax Identification Number.
  * `customer_name` *(string, optional)* – The legal name of the customer. Used for name match checks.
  * `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 lookups.
  * `county` *(string, optional)* – County or district name (if applicable).
  * `postal_code` *(string, optional)* – ZIP or postal code for geolocation support.
  * `ip_address` *(string, optional)* – User’s IP address to infer location when address fields are missing.
</Accordion>

***

## Response Fields

A successful response will include:

<Accordion title="Response Fields">
  * `valid` *(boolean)* – Whether the Tax ID is valid.
  * `customer_name` *(string)* – The official name associated with the Tax ID.
  * `customer_name_match` *(boolean)* – Whether the provided name matches the registry.
  * `customer_type` *(string)* – Entity classification. One of:
    * `B2C` – Business to Consumer
    * `B2B` – Business to Business
    * `PRISCH` – Private School
    * `PRIEDUI` – Private Educational Institution (Non-School)
    * `GOV` – Government Entity
    * `PUBSCH` – Public School
    * `PUBEDU` – Public Educational Institution (Non-School)
    * `PRIHOS` – Private Hospital
    * `PUBHOS` – Public Hospital
    * `NGO` – Non-Governmental Organization
  * `country` *(string)* – Country associated with the registry.
  * `state` *(string)* – State or region returned from the registry (if available).
  * `address` *(string)* – Registered address (if available).
  * `source` *(string)* – Authority or data source used for validation (e.g., VIES, GSTIN).
  * `validation_timestamp` *(string)* – ISO timestamp of the validation event.
  * `request_id` *(string)* – Unique reference for tracing and support.
</Accordion>

***

## Usage Tips

Use this endpoint during:

* Onboarding of B2B or institutional customers
* Validation of VAT/GST registration numbers
* Compliance and audit workflows requiring verified registry data


## OpenAPI

````yaml POST /v1/tax/id-validate
openapi: 3.0.1
info:
  title: Antei API Reference
  description: >-
    Programmatic access to Antei’s platform. Use this API to manage core objects
    and retrieve taxation insights.
  version: 1.0.0
  license:
    name: MIT
  contact:
    name: Antei Developer Support
    email: support@antei.com
    url: https://antei.com
servers:
  - url: https://api.antei.com
security:
  - bearerAuth: []
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)
    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

````