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
- for example, you need to use
- Deprecation of
device
objects - Deprecation of
risk_scores
- Updates to the events, instrument and entity objects
entity_type
is optionalbusiness_data
is deprecateduser_data
is optionalinstrument_subtype
is now publicly supported- deprecation of
sender_source
andreceiver_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.