Best Practices

Best Practices when sending Data to Unit21


  • The Business Team should collaborate with engineers to decide what key data (i.e. custom data) needs to be in the system since Business team members are the end users of the system.
  • Give the Unit21 implementation team your set of initial launch rules (6-12) that you want go live with so that we could determine what data values are needed for your data integration
  • Send Entities first, then send Instruments and associate them with the entities, then send transaction events and tie them with the Entities and Instruments via sender and receiver fields accordingly
  • More population of the standard fields in entities, instruments and transaction events has the following advantages:
    • More filter options with rules
    • Investigators & analyst will have a more comprehensive view when managing alerts
  • Don’t send in blank strings (“”) or null if fields are missing, instead just exclude the field from the request altogether


  • Entity ID needs to be unique!
  • User/Business “Entity Type”, must be finalized because it cannot be changed later
  • If you are filing SARs, the phone number field should exclude +1 if the profile is US
  • If you are not filing SARs and using IDV Verifications, then include the +1 if profile is US
  • Country Code should be two letter abbreviations (i.e. US for United States)
  • If a country is in the United States, then State should also be two letter abbreviations
  • An entity record (a user or a business) can be linked to multiple Instruments (ie. Accounts, Wallets)


  • Instrument ID needs to be unique!
  • Whenever possible, always link an Instrument with an entity so that an “account” is associated with a person
  • Multiple instruments can be associated to a single entity
  • Country Code should be two letter abbreviations (i.e. US for United States)
    • If a country is in the United States, then State should also be two letter abbreviations


  • Event ID needs to be unique!
  • Remember that a transaction event brings two entities (a sender and receiver user or business) and two Instruments (a sender or receiver account or wallet) together with a Sent and Received Amount (FX agnostic) and a baseline “Amount” as well (typically USD).
    • Here’s an example: James (while in Canada) pays Best Buy (in US) $1,000 for a computer purchase through his credit card. The transaction will look like this in Unit21:
  • If either side (Sender or Receiver), has your company’s name on it, this is most likely wrong! There’s no reason for your company name’s to be in the transaction because you are monitoring the transactions of counter parties. If your company is the middleman of funds, then your transaction needs to show the sender and receiver names of those counter parties (without including your company into the mix).
  • No Negative Numbers in amount, sent & received amount or custom fields
  • Include values for Event Subtypes! With a banking example, an event subtype can be, deposit, withdrawal, ACH, wire, etc. The business team can build rules and apply filters on subtypes if they want their rules to only look at “ACH” transactions. Without subtypes, they will rake in all transactions and end up having many false positives
  • Sent & Received Amount can be any currency
  • Enter Sent & Received Currency Type if applicable (i.e. CAD, AUD, etc.)
  • By “default, “Amount" is set to USD. This field is your base currency. If you have another base currency other than USD, you may inform your implementation manager and we could change it to your desired base currency.
  • Most of the thresholds in rule settings are based on the “Amount” field. If by chance you don’t have a base “amount”, meaning it could be various currencies, then use tags to note the currency, i.e. currency: CAD. Then inform the implementation team to replace the default USD with a blank on amount if you do not have base currency. After that’s done, your amount field will be i.e. “1000” and tag of “Currency:CAD” in the transaction would make this 1,000 CAD transaction.
  • Country Code should be two letter abbreviations (i.e. US for United States). If the country is in the United States, then states should also be two letter abbreviations.
  • Important: For functional testing purposes, send in transactions and spread them out over a 2-3 month period so that you could functionally test the rules. Refrain from concentrating all transactions into a tight time range (i.e. all transactions are dated 1/1/2022) because you will not be able to test rules with a specific look-back period.


  • Device IDs need to be unique!
  • If you are using NFTs or unique assets, send in the NFT asset ID as a Device ID
  • Use “Type” to distinguish the NFT (baseball card, artwork, etc.)
  • Custom Fields to put NFT details on it (bar code string)
  • Flatten your data and bring data into dedicated field to preserve the data’s character (do not jam all values into one single string and load into one field)

Custom Fields

  • Do not put sub fields within one custom fields
  • Do not nest custom fields into objects or arrays (i.e. “first names”, ”last names”, “SSN” in one field)
  • Don’t mix the data types. For a particular field, if one value is an integer type, they should all be an integer type. Don’t mix strings and integers
  • Use custom fields to represent an existing taxonomy. For example, custom data for an entity might represent a customer tier or other internal piece of metadata,
    • Metadata in custom fields is especially helpful when finding entities/alerts/instruments in the system based on that metadata


  • Use tags to represent an existing taxonomy. For example, categories like Product Lines, Risk Levels, Regions, etc. These tags would group certain entities, instruments, and events together
  • Tags are useful for reporting
  • Can be used in conjunction with workflow buttons
  • DO NOT use individual data points for tags. Proliferation of tags will cause performance issues.