Events have two types, transaction events and action events:

  • Transaction events are any monetary flow that is sent or received by an entity on your system.
  • Action events are non-monetary changes of state that occur on your system, e.g. user logins.

The /events endpoint sends and receives data about significant actions that occur with an entity or instrument on your system.

ENDPOINT

DESCRIPTION

POST /events/create

Creates an event.

POST /entities/list

Retrieves a list of all events.

PUT /events/<unit21_id>/update

Updates an existing event.

GET /events/<unit21_id>

Retrieves an existing event.

Batch Event Requests

The /entities/create API accepts batch uploads:

  • each batch must contains no more than 250 entities,
  • and the total size of the POST body must be smaller than 100mb.
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
            }
        }
    ]
}'

When uploading a batch of entities, 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 entities 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 /entities/update API, Unit21 will not update the event with the newly provided fields, nor will it insert a new event into our system.

Event Subtypes for Transactions

Transaction subtypes provide a way to differentiate between, filter, and select transactions of different types.

Here are recommended (and optional) transaction subtypes:

Subtype

Description

ach

ACH transfers to/from a bank account

deposit

Funding events from your users' external accounts to your system accounts

withdrawal

Users withdrawing monetary value from your system accounts to their external accounts

p2p

Transfer of value between users on your platform

purchase

Goods purchases, rentals, card network payments made by the user

refund

Reversal of any transaction into the user's account

reversal

Alterations to a previous transaction

debit

Monetary transfer into the target user's account

loan_issued

Loan given by the platform to the user

loan_payment

Loan repayment given or received by the user

Event Subtypes for Actions

Action subtypes provide a way to differentiate between, filter, and select transactions of different types.

Here are recommended (and optional) action subtypes:

Subtype

Description

user_login

Event log of a registered user logging in to your platform

user_logout

Event log of a registered user logging out of your platform

user_access

Event log of a registered user accessing

user_profile_update

Update event of a user's profile e.g. a user updating their shipping address

user_deletion

Permanent user deletion from the platform

user_blocked

User blocked on the platform

user_suspended

Temporary suspension of the user on the platform

communication

Event log detailing a communication/messaging event involving users on your platform and/or your customer contact teams

dispute

Event log detailing disputes and complaints filed user on your platform

user_referral

Event log detailing any referral activity initiated by existing users on your platform

promotion_applied

Event log detailing any application of promotions to a user on your platform

Action Types for Actions

Possible values of action_type are:

Action Type

SIGNUP

LOGIN

LOGOUT

BLOCK

CLOSE

ACTIVATE

FORGOT_PASSWORD

PASSWORD_RESET

PROMO_CODE_USE

PROFILE_CHANGE

Modify Event Tags

Modifying an event's tags can be achieved through the /events/update endpoint (or via implicit upserts through /events/create). Event-associated tags are considered as list-types on objects, so the standard list merge strategies apply. By default, newly specified tags in a request are unioned with the existing tags on the event.

Tag deletion can either be achieved with the replace (full replace of the entire list) or difference (set-difference) list merge strategies.

Delete Events

Deleting events is not allowed.

Options for the Endpoint

curl -X POST \
  https://<API_ENDPOINT>/v1/entities/create \
  -H 'Content-Type: application/json' \
  -H 'u21-key: <YOUR_API_KEY>' \
  -d '{
    "options": {
      "monitor": false,
      "resolve_geoip": true,
      "merge_custom_data": true,
      "list_merge_strategy": "union"
    }
  }'

The following fields are options for the endpoint:

Field

Type

Description

workflow_id

String

A unique identifier defined during workflow creation. Note that some workflows do not allow for synchronous responses.

run_verifications

Boolean

Whether or not to execute a verification workflow for the uploaded entity/entities.

synchronous_response

Boolean

Whether or not to immediately execute the workflow & receive a verification response as part of the API request response. If synchronous_response is true for a workflow that doesn't allow synchronous responses, this will throw an error.

include_full_response

String

Include the full, raw, verification results. This option can only be used if synchronous_response is set to true, or a 400 Bad Request will be returned. This is an optional field and will default to false.

resolve_geoip

Boolean

Whether or not to resolve the geographic location from the provided IP address (in the digital data section). Defaults to true if at least one value of an ip_address is provided in digital_data.ip_addresses. If resolve_geoip is set to true but no values are provided in digital_data.ip_addresses, an exception will be thrown. If resolve_geo_ip is set to true but the IP address provided is invalid or cannot be resolved, no exception will be thrown.

merge_custom_data

Boolean

Only relevant for updates/upserts, ignored otherwise. Default is false.

list_merge_strategy

String

Only relevant for updates/upserts, ignored otherwise. Possible values are union, replace, difference. Default is union.