# Tax identities · Customer API

> Customer API reference for tax identities: GET /tax-identities, PUT /tax-identities, DELETE /tax-identities/{id}.

> Markdown version of https://kanorio.com/en/developers/customer-api/tax-identities. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp

Base URL: `https://{site}/api/v1/customer` · [Errors](https://kanorio.com/en/developers/basics/errors) · [Pagination](https://kanorio.com/en/developers/basics/pagination)

### List the customer's tax IDs

`GET /tax-identities`

- Stability: beta

One per country and type, with the verification status against the public registry where one exists.

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `taxIdentities` | object[] | yes | — |
| `taxIdentities[].id` | string | yes | — |
| `taxIdentities[].country` | string | yes | — |
| `taxIdentities[].type` | string | yes | — |
| `taxIdentities[].value` | string | yes | As entered. |
| `taxIdentities[].normalized` | string | yes | — |
| `taxIdentities[].status` | "PENDING" \| "VALID_FORMAT" \| "VERIFIED" \| "NOT_FOUND" \| "UNAVAILABLE" \| "INVALID_FORMAT" | yes | Verification against the public registry; informational only. |
| `taxIdentities[].name` | string \| null | yes | — |
| `taxIdentities[].address` | string \| null | yes | — |
| `taxIdentities[].registryName` | string \| null | yes | Name recorded by the registry when VERIFIED. |
| `taxIdentities[].registryStatus` | string \| null | yes | — |
| `taxIdentities[].attribution` | object \| null | yes | Open-data attribution to show next to registry data. |
| `taxIdentities[].attribution.provider` | string | no | — |
| `taxIdentities[].attribution.providerEn` | string | no | — |
| `taxIdentities[].attribution.dataDate` | string | no | — |

```bash
curl -X GET "https://{site}/api/v1/customer/tax-identities" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN"
```

### Add or update a tax ID

`PUT /tax-identities`

- Stability: beta

Keyed by country and type (type defaults to the country's first registered type). Format and checksum follow the shared business-registry rules; a changed number is re-verified asynchronously. Verification results are informational and never block checkout.

**Request body**

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | string | yes | ISO 3166-1 alpha-2. |
| `type` | string \| null | no | Tax ID type (for example tw_vat, jp_trn, eu_vat); defaults to the country's first registered type. |
| `value` | string | yes | — |
| `name` | string \| null | no | Registered name for invoices. |
| `address` | string \| null | no | Registered address for invoices. |

**Response** (200)

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `taxIdentity` | object | yes | — |
| `taxIdentity.id` | string | yes | — |
| `taxIdentity.country` | string | yes | — |
| `taxIdentity.type` | string | yes | — |
| `taxIdentity.value` | string | yes | As entered. |
| `taxIdentity.normalized` | string | yes | — |
| `taxIdentity.status` | "PENDING" \| "VALID_FORMAT" \| "VERIFIED" \| "NOT_FOUND" \| "UNAVAILABLE" \| "INVALID_FORMAT" | yes | Verification against the public registry; informational only. |
| `taxIdentity.name` | string \| null | yes | — |
| `taxIdentity.address` | string \| null | yes | — |
| `taxIdentity.registryName` | string \| null | yes | Name recorded by the registry when VERIFIED. |
| `taxIdentity.registryStatus` | string \| null | yes | — |
| `taxIdentity.attribution` | object \| null | yes | Open-data attribution to show next to registry data. |
| `taxIdentity.attribution.provider` | string | no | — |
| `taxIdentity.attribution.providerEn` | string | no | — |
| `taxIdentity.attribution.dataDate` | string | no | — |
| `created` | boolean | no | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `VALIDATION` | 400 | — |
| `INVALID_TAX_ID` | 400 | — |
| `UNSUPPORTED_COUNTRY` | 400 | — |

```bash
curl -X PUT "https://{site}/api/v1/customer/tax-identities" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Remove a tax ID

`DELETE /tax-identities/{id}`

- Stability: beta

**Parameters**

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `id` | path | string | yes | — |

**Errors**

| Code | Status | When |
| --- | --- | --- |
| `NOT_FOUND` | 404 | — |

```bash
curl -X DELETE "https://{site}/api/v1/customer/tax-identities/{id}" \
  -H "Authorization: Bearer $KANORIO_CUSTOMER_TOKEN"
```
