Entity API Idempotency Support - Introduction to Tazapay

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

Entity API Documentation

​Summary

​How It Works

​Individual entities

​Business entities

​Behavior on Duplicate

​Affected Endpoints

​Relevant Links