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

# Entity API Idempotency Support

**Release Type:** Enhancement

## Summary

The Entity API now supports idempotency for entity creation and updates. When a request is submitted with identifying fields that match an existing entity, the API returns the response of the first created entity. No error is returned and no duplicate entity is created.

## How It Works

Duplicate detection evaluates the request against two sets of fields.

**Scope fields** narrow the check to entities within the same account context:

| Field          | Description                                 |
| -------------- | ------------------------------------------- |
| `name`         | Full name of the entity                     |
| `on_behalf_of` | Account the entity was created on behalf of |
| `vertical`     | Industry vertical of the entity             |

**Identity fields** confirm uniqueness. If the request includes an email address, national identification number, or registration number, those fields are matched globally across the account, independent of name. Fields are evaluated in priority order and the earliest-created match is returned.

### Individual entities

| Priority | Field(s)                                                                            |
| -------- | ----------------------------------------------------------------------------------- |
| 1        | `email`                                                                             |
| 2        | `national_identification_number.type` + `national_identification_number.number`     |
| 3        | `name` + `registration_address` (country, address line 1, city, state, postal code) |

### Business entities

| Priority | Field(s)                                               |
| -------- | ------------------------------------------------------ |
| 1        | `registration_number` + `registration_address.country` |
| 2        | `name`                                                 |

All field comparisons are case-insensitive and whitespace-trimmed.

## Behavior on Duplicate

When a duplicate is detected, the API returns the response of the first created entity with an HTTP `200 OK`, identical to a standard successful response. No error is returned and no new entity is created.

## Affected Endpoints

* `POST /v3/entity` — duplicate detection applied on creation
* `PUT /v3/entity/{id}` — duplicate detection applied on update
* `POST /v3/entity/{id}/submit` — duplicate detection applied on submission

## Relevant Links

1. [Entity API Documentation](/API-Reference/tazapay-api/entity/entity)