IMPORTANT: Breaking Changes to the Unit21 API
Unit21 ID and its associated fields (like
previously_existed) will be deprecated for Entity, Events, and Instrument objects. Additionally, the List Entities, Events, and Instruments endpoints will be deprecated.Your integration may be affected if you utilize any of the APIs, webhooks, or exports listed here: https://docs.unit21.ai/page/api-changes
⏰ Action Required: Please check and update your integration by September 30, 2023.
Entities are businesses or users that have transactions on your platform.
The /entities endpoint can create, list, and update entities.
It can also be used to run identification/verification workflows on an entity.
When you create a transaction via API, it is typically between two entities. Either or both of those entities can be marked as 'external' (using a key which defaults to 'internal').
Internal versus external entities:
For an internal entity:
- if an entity with that org/external ID pair exists in the system, the transaction is tied to that entity
- if an entity with that org/external ID pair does not exist in the system, a placeholder entity is created and the transaction is tied to that entity. That placeholder can still e.g. trigger entity-based alerts etc.
for an external entity: - if an entity with that org/external ID pair exists in the system, things are handled identically to internal entities
- if not, no entity is created. The entity is treated as 'external' and alerts based on that entity will not show the entity.
- If an entity with that org/external id is LATER CREATED, then all of the transactions that involved that external id/org pair as an external entity will be immediately associated with the new entity, potentially triggering multiple entity-based alerts based on old transactions.