Schema 2.0 - API update and object deprecations

At Unit21, we are updating out APIs and object schemas to better address our customer data and their data structures.

These updates will happen over Q3 and Q4 as we work with our customers to ensure a smooth transition.
The system is backwards compatible in the meantime.

What does it mean?

The APIs updates are as follows:

• Deprecation of unit21_id instrument and entity endpoints
  • for example, you need to use /v1/{org_name}/entities/{entity_id} instead of /v1/entities/{unit21_id}
  • use of a unique object ID for entity_id or instrument_id is required
  • the unit21_id will remain for items such as rules or verifications
• Deprecation of device objects
• Deprecation of risk_scores
• Updates to the events, instrument and entity objects
  • entity_type is optional
  • business_data is deprecated
  • user_data is optional
  • instrument_subtype is now publicly supported
  • deprecation of sender_source and receiver_source in transactions
• Deprecation of the list_merge_strategy option on endpoints
• New programmatic export endpoints
• New file import endpoints

Many of the optional object field will remain backwards compatible. For example, you can still send in business_data and Unit21 will save it; however, business_data will not be usable in the Dashboard (i/e can't be used for rules).

Organizations that rely on devices and risk scores will be grandfathered in.

Unit21 expects organizations to use custom_data to send information such as risk scores into our system.

Device objects can be sent in as Instruments or Entities instead. As device objects are deprecated, the instrument object is recommended instead as it can be flagged by rules and reviewed in a case/alert investigation. Here is an example to describe a company laptop:

{
     "instrument_id": "Mac-Laptop-0104",
     "instrument_type": "company",
     "instrument_subtype": "mac-air-m2",
     "source": "internal",
     "status": "deployed",
     "registered_at": 1670526209,
     "digital_data": {
          "client_fingerprints": [
               "00:1A:C2:7B:00:47" //unique MAC address of the laptop
          ]
     }
}

What does it look like?

Please look at our API documentation to view live changes.