Some examples of how you can send batches of entities, events, and instruments in one request.
Batch Create Entities
The /entities/create API accepts batch uploads:
- each batch must contains no more than 1000 entities,
- and the total size of the POST body must be smaller than 1MB.
When uploading a batch of entities, any entity-level options will be ignored; only the top-level options provided will be used. These options are applied globally.
The following snippet shows a valid request body to batch send two entities:
curl -X POST \
https://<API_ENDPOINT>/v1/entities/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"entities": [
{
"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"
}
},
{
"general_data": {
"entity_id": "371c4d7b-0563-4685-aab2",
"entity_type": "business",
"entity_subtype": "payments",
"status": "active",
"registered_at": 1572673226
},
"business_data": {
"business_name": "Global Liquids LLC",
"corporate_tax_id": "434-455-3167",
"account_holder_name": "John Smith",
"registered_state": "CA",
"registered_country": "US",
"doing_business_as": "Global Liquids LLC"
}
}
],
"options": {
"identity_verifications": {
"workflow_id": "sanctions_check_1",
"run_verifications": true,
"synchronous_response": false
},
"upsert_on_conflict": true,
"resolve_geoip": true,
"merge_custom_data": true,
"list_merge_strategy": "union"
}
}'
If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Missing required field `general_data`"
}
A successful response contains a count of all the entities processed in the batch along with a list of objects containing three fields.
The list allows you to map the entity_id passed to our API with our internal unit21_id.
The response also indicates whether this entity previously existed or not.
HTTP/1.1 200 OK
Content-Type: application/json
{
"count": 2,
"entities": [
{
"entity_id": "371c4d7b-0563-4685-aab1",
"unit21_id": "43247",
"previously_existed": false
},
{
"entity_id": "371c4d7b-0563-4685-aab2",
"unit21_id": "43248",
"previously_existed": true
}
]
}
For entities that already exist in our system, previously_existed will be true:
- If the call is to
/entities/update; Unit21 will update an entity with the newly provided fields. - If the call is to
/entities/create; Unit21 will treat it as an upsert and an update on the existing entity is performed
Batch Create Events
The /events/create API accepts batch uploads:
- each batch must contains no more than 1000 events,
- and the total size of the POST body must be smaller than 1MB.
Entity-level options are ignored. Instead, send options as its own
second-level field (inside the events object). These options are applied
globally.
The following snippet shows a valid request body to batch send two events:
curl -X POST \
https://<API_ENDPOINT>/v1/events/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"events": [
{
"general_data": {
"event_id": "txnBulk-1",
"event_type": "transaction",
"event_subtype": "ach",
"event_time": 1572673226,
"status": "incomplete",
"tags": [
"account_type:market2",
"sector:europe"
]
},
"transaction_data": {
"sent_amount": 30983.48,
"sent_currency": "usd",
"sender_entity_id": "userA",
"sender_entity_type": "user",
"sender_source": "internal",
"sender_instrument_id": "instrumentA",
"received_amount": 9233.33,
"received_currency": "eur",
"receiver_entity_id": "userB",
"receiver_entity_type": "user",
"receiver_source": "internal",
"receiver_instrument_id": "instrumentB",
"amount": 30983.48,
"exchange_rate": 1.11
}
},
{
"general_data": {
"event_id": "txnBulk-2",
"event_type": "transaction",
"event_subtype": "wire",
"event_time": 1572683226,
"status": "incomplete",
"tags": [
"account_type:market2",
"sector:europe"
]
},
"transaction_data": {
"sent_amount": 5555.48,
"sent_currency": "usd",
"sender_entity_id": "userA",
"sender_entity_type": "user",
"sender_source": "internal",
"sender_instrument_id": "instrumentA",
"received_amount": 5555.48,
"received_currency": "usd",
"receiver_entity_id": "userB",
"receiver_entity_type": "user",
"receiver_source": "internal",
"receiver_instrument_id": "instrumentB",
"amount": 5555.48
}
}
],
"options": {
"monitor": true,
"linked_entity": "both",
"merge_custom_data": false,
"list_merge_strategy": "union"
}
}'
When uploading a batch of events, any event-level options will be ignored; only the top-level options provided will be used.
If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Missing required field `event_id`"
}
The response contains a count of all the events processed in the batch along with a list of objects containing three fields. The list allows you to map the event_id passed to our API with our internal unit21_id. The response also indicates whether this event previously existed or not.
HTTP/1.1 200 OK
Content-Type: application/json
{
"count": 2,
"events": [
{
"event_id": "txnBulk-1",
"previously_existed": false,
"unit21_id": "1572463931"
},
{
"event_id": "txnBulk-2",
"previously_existed": true,
"unit21_id": "1572463936"
}
]
}
For events that previously already existed in our system, previously_existed will be true.
Unlike the /events/update API, Unit21 will not update the event with the newly provided fields, nor will it insert a new event into our system.
Batch Create Instruments
The /instruments/create API accepts batch uploads:
- each batch must contains no more than 1000 instruments,
- and the total size of the POST body must be smaller than 1MB.
When you create a batch of instruments, you MAY use all the objects
available when creating a single instrument. There are only two differences:
- Each instrument batch object is sent in the
instrumentsarray. - The
optionsobject should be outside of theinstrumentsarray. This overrides alloptionscontained in a single instrument objects.
Here's a minimal example of a batch request to create two instruments:
curl -X POST \
https://<API_ENDPOINT>/v1/instruments/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"instruments": [
{
"instrument_id": "3234-sdghfdf-3332",
"instrument_type": "account",
"source": "internal",
"status": "active",
"registered_at": 1572672326,
"parent_instrument_id": "3234-sdghfdf-3331",
"custom_data": {
"activated_at": 1572679326
}
},
{
"instrument_id": "3234-dfsasfr-3334",
"instrument_type": "account",
"source": "internal",
"status": "dormant",
"registered_at": 1572672326,
"parent_instrument_id": "3234-sdghfdf-3331",
"custom_data": {
"activated_at": 1572679326
}
}
]
}'
When uploading a batch of instruments, any instrument-level options will be ignored; only the top-level options provided will be used.
If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Unexpected field `instrument_idd`"
}
The response contains a count of all the instruments processed in the batch along with a list of objects containing three fields. The list allows you to map the instrument_id passed to our API with our internal unit21_id. The response also indicates whether this instrument previously existed or not.
HTTP/1.1 200 OK
Content-Type: application/json
{
"count": 2,
"instruments": [
{
"instrument_id": "3234-sdghfdf-3332",
"unit21_id": "49073",
"previously_existed": false
},
{
"instrument_id": "3234-dfsasfr-3334",
"unit21_id": "49074",
"previously_existed": true
}
]
}
Batch Alert Requests
The /alerts/create API accepts batch uploads:
- each batch must contains no more than 1000 alerts,
- and the total size of the POST body must be smaller than 1MB.
curl -X POST \
https://<API_ENDPOINT>/v1/alerts/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"alerts": [
{
"alert_id": "alertB-{{randId}}",
"created_at": 1580763704,
"title": "Alert for fraud ring fool",
"description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
"status": "OPEN",
"tags": [
"source:intuit_internal"
],
"rules": [
"COLLUSION_3RD_PARTY",
"LAYERING_SCENARIO_A"
],
"events": [
{
"event_id": "txnA-{{randId}}",
"event_type": "transaction"
}
],
"entities": [
{
"entity_id": "userA-{{randId}}",
"entity_type": "user"
},
{
"entity_id": "businessA-{{randId}}",
"entity_type": "business"
}
],
"custom_data": {
"priority": "5"
}
},
{
"alert_id": "alertC-{{randId}}",
"created_at": 1580763704,
"title": "Alert for fraud ring fool",
"description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
"status": "OPEN",
"tags": [
"source:intuit_internal"
],
"rules": [
"COLLUSION_3RD_PARTY",
"LAYERING_SCENARIO_A"
],
"events": [
{
"event_id": "txnA-{{randId}}",
"event_type": "transaction"
}
],
"entities": [
{
"entity_id": "userA-{{randId}}",
"entity_type": "user"
},
{
"entity_id": "businessA-{{randId}}",
"entity_type": "business"
}
],
"custom_data": {
"priority": "5"
}
}
]
}'
When uploading a batch of alerts, any entity-level options will be ignored; only the top-level options provided will be used.
If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Missing required field `alert_id`"
}
The response contains a count of all the alerts processed in the batch along with a list of objects containing three fields. The list allows you to map the alert_id passed to our API with our internal unit21_id. The response also indicates whether this alert previously existed or not.
HTTP/1.1 200 OK
Content-Type: application/json
{
"alerts": [
{
"alert_id": "alertB-38f8e0Rwdf63nld71112345132UeUKFWE123",
"previously_existed": true,
"unit21_id": "9141601"
},
{
"alert_id": "alertC-38f8e0Rwdf63nld71112345132UeUKFWE123",
"previously_existed": false,
"unit21_id": "9219814"
}
],
"count": 2
}
For alerts that previously already existed in our system, previously_existed will be true.
Batch Case Requests
The /case/create API accepts batch uploads:
- each batch must contains no more than 1000 cases,
- and the total size of the POST body must be smaller than 1MB.
curl -X POST \
https://<API_ENDPOINT>/v1/cases/create \
-H 'Content-Type: application/json' \
-H 'u21-key: <YOUR_API_KEY>' \
-d '{
"cases": [
{
"case_id": "caseA}",
"start_date": 1588963704,
"end_date": 1589963704,
"title": "Imported case from internal flagging engine",
"description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
"status": "OPEN",
"tags": [
"source:intuit_internal"
],
"events": [
{
"event_id": "txnA",
"event_type": "transaction"
}
],
"entities": [
{
"entity_id": "userA",
"entity_type": "user"
},
{
"entity_id": "businessA",
"entity_type": "business"
}
],
"custom_data": {
"priority": "510"
}
},
{
"case_id": "caseB",
"start_date": 1588963704,
"end_date": 1589963704,
"title": "Imported case from internal flagging engine",
"description": "6 accounts that each have transacted $1M+ with each other over the last 4 days",
"status": "OPEN",
"tags": [
"source:intuit_internal"
],
"events": [
{
"event_id": "txnB",
"event_type": "transaction"
}
],
"entities": [
{
"entity_id": "userB",
"entity_type": "user"
},
{
"entity_id": "businessB",
"entity_type": "business"
}
],
"custom_data": {
"priority": "510"
}
}
]
}'
When uploading a batch of cases, any case-level options will be ignored; only the top-level options provided will be used.
If there are any data validation errors in the data that is passed (such as missing required fields) the entire batch request will fail with a 400 response code.
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json
{
"error_code": "invalid_input",
"message": "Missing required field `case_id`"
}
The response contains a count of all the cases processed in the batch along with a list of objects containing three fields. The list allows you to map the case_id passed to our API with our internal unit21_id. The response also indicates whether this case previously existed or not.
HTTP/1.1 200 OK
Content-Type: application/json
{
"cases": [
{
"case_id": "caseA",
"previously_existed": true,
"unit21_id": "7729780"
},
{
"case_id": "caseB",
"previously_existed": false,
"unit21_id": "9220307"
}
],
"count": 2
}
For cases that previously already existed in our system, previously_existed will be true.