Entities, Instruments and Event objects can include custom_data.
custom_data is an object that can include any information that agents may want to use for:
- adding data for models (rules) logic
- adding data to entities, instruments and events
- adding data from (external) 3rd parties
- adding data for verification workflows
- adding unsupported third-party verification data to entities (i.e., if you choose to use a vendor other than Socure or Middesk)
For example, an entity object can include:
"custom_data": {
"internal_notes": "Reviewed by Mitchell on 31 June 2019",
"reviewers": 3,
"login_time1": "1638384860",
"login_time3": 1638384860,
"date": "2018-06-21 00:00:00",
"daily_email": true,
"employees": ["John", "Anna", "Peter"],
"numbers": [0,1,2,3,4],
"socure_device_session_id": "12121212121212112"
}
The custom_data object accepts any JSON data. JSON data is in key:value format and the following types are accepted:
NESTED JSON UP TO 4 LAYERS DEEP IS SUPPORTED.
| JSON | EXAMPLE |
|---|---|
| nested json (up to 4 layers deep) | "president": { "name": "Zaphod Beeblebrox", "species": "Betelgeusian" } |
| string | "employer": "Google" |
| number | "logins": 3 |
| bool | "daily_email": true |
| null | "reviewers": null |
| arrays | "police_reports": [8354635,3566575,7896445] |
When you want to send data and times to Unit21 using custom data, please note:
| What you want do send: | Data type to use: | Example: |
|---|---|---|
| date time (epoch) | string (can also be sent in as a number if used for operations) | 1661814771 |
| date time (YYYY-MM-DD HH:MM:SS - please use UTC timezone) | string | 2018-06-21 00:00:00 |
| date (YYYY-MM-DD) | string | 2020-07-10 |
Do not use a . in a custom data key.
You can use a . in a value but not in the key of custom data:
totalAccountValue = 15000.00 is ok.
totalAccount.Value = 15000 is NOT ok.
Add data for Models (rules) logic
The custom_data can be used in the DMB and Scenario Models. If you want to use custom_data values in models (rules), the data should be independent key:value and it should be not nested. For example, we could flag transactions above $10,000.00 for entities with employers in the USA by using custom_data.employerLocation == US in the rule logic.
Add data to Entities, Instruments and Events
Some agents may want to include the sender or receiver's current funds in a transaction and can do so using the custom_data object. For example: custom_data.totalaccountvalue == $15458.
Add data from external parties
You can add data from 3rd parties using custom_data such as a credit score, DoD information, employer ID #, threat level, pseudonym, green card #, and so on. For example: custom_data.EmployeeNumber == 678912.
Custom data is typically used to add verification results from vendors not supported by Unit21 such as Experian.credit_score == 680.
Add data for Socure "DocV" and "Device Risk" verification workflows
When using Socure for "DocV" and "Device Risk" verification purposes, socure_device_session_id and socure_document_uuid must be included in the entities custom data.