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.
Events have two types, transaction events and action events:
- Transaction events are any monetary flow that is sent or received by an entity on your system.
- Action events are non-monetary changes of state that occur on your system, e.g. user logins.
The /events endpoint sends and receives data about significant actions that occur with an entity or instrument on your system.
Event upserts versus updates:
- When sending a create request for an event (transaction or action event) that does not yet exist, any queries to read that event return a HTTP 423 LOCKED until that event has been fully processed (usually takes roughly 1 second, but can in some cases take significantly longer).
- When sending a create request for an event (transaction or action event) that already exists, and they have update-on-conflict turned on, any queries to read that event will return the old (non-updated) data until that event has been fully processed (usually takes roughly 1 second, but can in some cases take significantly longer).
- When sending an update event request for an event that exists, any queries to read that event return the old (non-updated) data until that event has been fully processed (usually takes roughly 1 second, but can in some cases take significantly longer).
Event Subtypes for Transactions
Transaction subtypes provide a way to differentiate between, filter, and select transactions of different types.
Here are recommended (and optional) transaction subtypes:
| Subtype | Description |
|---|---|
ach | ACH transfers to/from a bank account |
deposit | Funding events from your users' external accounts to your system accounts |
withdrawal | Users withdrawing monetary value from your system accounts to their external accounts |
p2p | Transfer of value between users on your platform |
purchase | Goods purchases, rentals, card network payments made by the user |
refund | Reversal of any transaction into the user's account |
reversal | Alterations to a previous transaction |
debit | Monetary transfer into the target user's account |
loan_issued | Loan given by the platform to the user |
loan_payment | Loan repayment given or received by the user |
Event Subtypes for Actions
Action subtypes provide a way to differentiate between, filter, and select transactions of different types.
Here are recommended (and optional) action subtypes:
| Subtype | Description |
|---|---|
user_login | Event log of a registered user logging in to your platform |
user_logout | Event log of a registered user logging out of your platform |
user_access | Event log of a registered user accessing |
user_profile_update | Update event of a user's profile e.g. a user updating their shipping address |
user_deletion | Permanent user deletion from the platform |
user_blocked | User blocked on the platform |
user_suspended | Temporary suspension of the user on the platform |
communication | Event log detailing a communication/messaging event involving users on your platform and/or your customer contact teams |
dispute | Event log detailing disputes and complaints filed user on your platform |
user_referral | Event log detailing any referral activity initiated by existing users on your platform |
promotion_applied | Event log detailing any application of promotions to a user on your platform |
Action Types for Actions
Possible values of action_type are:
| Action Type |
|---|
| SIGNUP |
| LOGIN |
| LOGOUT |
| BLOCK |
| CLOSE |
| ACTIVATE |
| FORGOT_PASSWORD |
| PASSWORD_RESET |
| PROMO_CODE_USE |
| PROFILE_CHANGE |