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

# Unified Tax Calculation & Validation

> Calculate tax rates and validate tax IDs in a single unified call.

Use this endpoint to perform both tax rate calculation and tax ID validation in one unified request. Ideal for checkout, invoicing, or compliance flows where both functions are needed together.

***

### Request Parameters

You must send a request body with the following fields:

<Accordion title="Request Parameters">
  <Accordion title="Product & Delivery Parameters">
    * `product_id`: *(string, optional)*\
      Internal product ID

    * `product_category`: *(string, optional)*\
      Category name (used if no `product_id` is provided). Must be one of:
      * `CSS` – Custom Software
      * `DTSP` – Dev & Tech Support Services - With Product
      * `DAW` – Digital Audio Works
      * `DAVW` – Digital Audio-Visual Works
      * `DB` – Digital Books
      * `DP` – Digital Photographs
      * `IAAS` – Infrastructure-as-a-Service (IaaS)
      * `PAAS` – Platform-as-a-Service (PaaS)
      * `SAAS` – Software-as-a-Service (SaaS)
      * `PRSFT` – Pre Written Software
      * `RNGT` – Ringtone
      * `DSWS` – Data & Web Hosting Services
      * `GMO` – Gaming
      * `SSS` – Streaming Services
      * `DTSS` – Development and Technical Support Services - Separate
      * `INGMO` – In-Game Purchases

    * `is_security`: *(boolean, optional)*\
      Boolean flag to indicate if the product is a financial security

    * `delivery_method`: *(string, required)*\
      Must be one of:
      * `CLOUD` – On Cloud Services
      * `PHYSICAL` – Physical Transfer
      * `DOWN` – Electronically Transferred
  </Accordion>

  <Accordion title="Customer Paramters">
    * `customer_id`: *(string, optional)*\
      Internal customer identifier

    * `customer_type`: *(string, optional)*\
      Required if no `customer_id` is provided. Allowed values:
      * `B2C` – Business to Customer
      * `B2B` – Business to Business
      * `PRISCH` – Private Schools
      * `PRIEDUI` – Private Educational Institutions besides Schools
      * `GOV` – Government Entities
      * `PUBSCH` – Public Schools
      * `PUBEDU` – Public Educational Institutions besides Schools
      * `PRIHOS` – Private Hospitals
      * `PUBHOS` – Public Hospitals
      * `NGO` – Non Government Organisations
  </Accordion>

  <Accordion title="Location Parameters">
    * `country`: *(string, required)*\
      Country code (ISO 3166 Alpha-2)

    * `state`: *(string, optional)*\
      Region or state

    * `county`: *(string, optional)*\
      Local jurisdiction

    * `postal_code`: *(string, optional)*\
      ZIP or postal code

    * `ip_address`: *(string, optional)*\
      Used for geolocation if address is unavailable
  </Accordion>

  <Accordion title="Tax ID Validation Parameters">
    * `tax_id`: *(string, required)*\
      Tax ID to validate

    * `customer_name`: *(string, optional)*\
      Used for name matching
  </Accordion>
</Accordion>

***

### Response Fields

The response includes two major sections: **Tax Calculation** and **Tax ID Validation**.

<Accordion title="Response Fields">
  <Accordion title="Tax Calculation Fields">
    * `taxability`: *(boolean)*\
      Whether the product is taxable

    * `country_rate`: *(integer)*\
      Country-level tax rate (×1000)

    * `state_rate`: *(integer)*\
      State-level tax rate (×1000)

    * `county_rate`: *(integer)*\
      County-level tax rate (×1000)

    * `additional_rate`: *(integer)*\
      Surcharges (×1000)

    * `special_rate`: *(integer)*\
      Special region-specific rates (×1000)

    * `total_rate`: *(integer)*\
      Total tax rate (×1000)

    * `reverse_charge_applicable`: *(boolean)*\
      Whether reverse charge applies

    * `exempt`: *(boolean)*\
      Whether the transaction is tax-exempt
  </Accordion>

  <Accordion title="Tax ID Validation Fields">
    * `tax_id_valid`: *(boolean)*\
      Whether the tax ID is valid

    * `customer_name_registry`: *(string)*\
      Name as retrieved from registry (if available)

    * `customer_name_match`: *(boolean)*\
      Whether provided name matches registry name

    * `customer_type`: *(string)*\
      Inferred or validated customer type

    * `validated_country`: *(string)*\
      Country confirmed by registry

    * `validated_state`: *(string)*\
      State confirmed by registry

    * `registry_address`: *(string)*\
      Address from registry (if available)

    * `validation_source`: *(string)*\
      Source used (e.g., `VIES`, `GSTN`)

    * `validation_timestamp`: *(string)*\
      ISO timestamp of validation

    * `request_id`: *(string)*\
      Internal ID for audit and traceability
  </Accordion>
</Accordion>

***

### Notes

<Card>
  <Warning>All rate fields are integers multiplied by 1000 (e.g., `19000` = `19%`)</Warning>
  <Note>If both `product_id` and `product_category` are provided, `product_id` takes priority</Note>
  <Note>If both `customer_id` and `customer_type` are provided, `customer_id` takes priority</Note>
  <Check>Reverse charge is determined automatically based on customer and jurisdiction</Check>
  <Tip>Ideal for invoicing systems, global checkout flows, or ERP automations</Tip>
</Card>


## OpenAPI

````yaml POST /v1/tax/unify
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/unify:
    post:
      tags:
        - Taxation
      summary: Unified Tax Rate + Tax ID Validation
      description: >-
        Calculate applicable tax rates and validate a customer's Tax ID using a
        single unified request.
      parameters:
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TaxUnifyRequest'
      responses:
        '200':
          description: Unified tax result and tax ID validation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TaxUnifyResponse'
        '400':
          description: Invalid input or missing fields
          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:
    TaxUnifyRequest:
      type: object
      required:
        - country
        - product_id
        - customer_id
        - tax_id
      properties:
        product_id:
          type: string
          description: ID of the product
        product_category:
          type: string
          description: Product category if ID is unavailable
          enum:
            - CSS
            - DTSP
            - DAW
            - DAVW
            - DB
            - DP
            - IAAS
            - PAAS
            - SAAS
            - PRSFT
            - RNGT
            - DSWS
            - GMO
            - SSS
            - DTSS
            - INGMO
        is_security:
          type: boolean
          description: Is the product a financial security?
        delivery_method:
          type: string
          enum:
            - CLOUD
            - PHYSICAL
            - DOWN
          description: Product delivery mode
        customer_id:
          type: string
          description: Customer ID
        customer_type:
          type: string
          enum:
            - B2C
            - B2B
            - PRISCH
            - PRIEDUI
            - GOV
            - PUBSCH
            - PUBEDU
            - PRIHOS
            - PUBHOS
            - NGO
          description: Customer type if ID not provided
        country:
          type: string
          description: Country code (ISO Alpha-2)
        state:
          type: string
          description: State/region
        county:
          type: string
          description: County/district
        postal_code:
          type: string
          description: Postal code
        ip_address:
          type: string
          description: IP address for geolocation
        tax_id:
          type: string
          description: Tax Identification Number
        customer_name:
          type: string
          description: Customer name (for validation match)
    TaxUnifyResponse:
      type: object
      properties:
        taxability:
          type: boolean
          description: Whether the product is taxable
        country_rate:
          type: integer
          description: Country-level tax rate (×1000)
        state_rate:
          type: integer
          description: State-level tax rate (×1000)
        county_rate:
          type: integer
          description: County-level tax rate (×1000)
        additional_rate:
          type: integer
          description: Any additional surcharge (×1000)
        special_rate:
          type: integer
          description: Special tax rate (×1000)
        total_rate:
          type: integer
          description: Final total rate (×1000)
        reverse_charge_applicable:
          type: boolean
          description: Is reverse charge applicable?
        exempt:
          type: boolean
          description: Is this transaction exempt from tax?
        tax_id_valid:
          type: boolean
          description: Whether the tax ID is valid
        customer_name_registry:
          type: string
          description: Name retrieved from tax registry
        customer_name_match:
          type: boolean
          description: Does the input name match registry?
        customer_type:
          type: string
        validated_country:
          type: string
        validated_state:
          type: string
        registry_address:
          type: string
        validation_source:
          type: string
          description: Source used for validation
        validation_timestamp:
          type: string
          format: date-time
        request_id:
          type: string
          description: Internal ID for auditing and tracing
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        status:
          type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````