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": 1638384860,
  "timestamp": "2012-03-40 05:12:41.000Z",
  "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]

If you want to send in an epoch, use a number type.
If you want to send in a date, use a string type.

📘

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.