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

# Tax ID Type Support for the Entity Object

**Release Type:** Enhancement

## Summary

The Entity object now supports a dedicated `tax_id_type` field alongside the existing `tax_id`. Previously, an entity's tax identifier could be captured, but its kind was not modelled as a first-class field. `tax_id_type` makes the identifier explicit and lets Tazapay validate the value against the entity's registration country and type.

As part of this change, `tax_id` has been removed as an option from the `type` enum of the entity's `national_identification_number` object. Tax identifiers are now represented exclusively through the entity-level `tax_id` and `tax_id_type` fields.

## What Changed

### New `tax_id_type` field

`tax_id_type` is an optional string enum. When `tax_id` is supplied, `tax_id_type` is required (and vice versa). Accepted values:

| Value    | Description                               | Country / Entity type     |
| -------- | ----------------------------------------- | ------------------------- |
| `ssn`    | Social Security Number                    | US · individual           |
| `itin`   | Individual Taxpayer Identification Number | US · individual           |
| `ein`    | Employer Identification Number            | US · business             |
| `pan`    | Permanent Account Number                  | India · any               |
| `cpf`    | Cadastro de Pessoas Físicas               | Brazil · individual       |
| `cnpj`   | Cadastro Nacional da Pessoa Jurídica      | Brazil · business         |
| `others` | Any other tax identifier                  | Any · any (not validated) |

The declared `tax_id_type` must be consistent with the entity's registration country and type — for example, a US-specific type such as `ein` cannot be declared for a non-US entity. For countries without a dedicated type, use `others`.

### `tax_id` removed from `national_identification_number.type`

The `tax_id` value is no longer accepted in the `type` enum of the `national_identification_number` object. Use the entity-level `tax_id` and `tax_id_type` fields instead.

## Affected Endpoints

* `POST /v3/entity` — Create Entity
* `PUT /v3/entity/{id}` — Update Entity
* `POST /v3/entity/{id}/submit` — Submit Entity
* `GET /v3/entity/{id}` — Fetch Entity (response now includes `tax_id_type`)
* `GET /v3/entity` — List Entities (response now includes `tax_id_type`)
* Entity webhooks — the entity `data` payload now includes `tax_id` and `tax_id_type`.

## Compatibility

This is a backward-compatible enhancement. `tax_id` and `tax_id_type` are optional; existing integrations that do not send them are unaffected. Integrations that previously sent `tax_id` as a `national_identification_number.type` should migrate to the entity-level `tax_id` / `tax_id_type` fields.

## Relevant Links

1. [Create Entity API Documentation](/api-reference/tazapay-api/create-entity)
2. [Entity API Documentation](/api-reference/tazapay-api/entity)
3. [Entity Webhooks](/api-reference/tazapay-api/entity-webhook)