Custom Data

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.

JSONEXAMPLE
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)string2018-06-21 00:00:00
date (YYYY-MM-DD)string2020-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.