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