Unit21's system creates placeholders for entities, instruments, or events that we expect to eventually be inserted in the system but don't yet exist.
When creating an entity using the /entities/create endpoint, you may include instrument objects:
curl -X POST \
https://<API_ENDPOINT>/v1/entities/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"general_data": {
"entity_id": "371c4d7b-0563-4685-aab1",
"entity_type": "user",
"entity_subtype": "payments",
"status": "active",
"registered_at": 1572673226
},
"user_data": {
"first_name": "John",
"middle_name": "Joseph",
"last_name": "Smith",
"day_of_birth": 14,
"month_of_birth": 1,
"year_of_birth": 1983,
"gender": "male",
"ssn": "733-99-5921"
},
"instrument_ids": [
"3234-sdghfdf-3332"
]
}'
In this case, a placeholders for instrument with instrument_id=3234-sdghfdf-3332 will be created if its is not already in the Unit21 system.
When the details are later provided through the /entities/create, /instruments/create, or /events/create APIs, the placeholder objects are populated with the newly provided information.
if a placeholder entity is updated and there are any field value mismatches a 400 error code will be returned.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Missing required field `business_data` for business type entity userA-38f8e0Rwdf6"
}
It does not matter whether you insert events and instruments before their corresponding entities or insert entities before their corresponding events and instruments. It is more important that the object be populated with relevant information at some point in time so that your fraud investigators can be more effective.