General Request Structure

All Events API request payloads should include the event_type field and data object:

{
  "event_type": "transaction",
  "data": {
    "supplemental_data": {}
  }
}

The fields inside the data object differ by Event Type and are defined in the API Reference. If you've mapped the Event Type to a Source Workflow, the Event data will be fed into the Source Workflow's evaluation payload.

Supplemental Data

Depending on how your Source Workflow or Journey is configured, there may be more fields in addition to the Event data that are required. Alloy will attempt to fetch these fields from previously supplied data when appropriate. If there is data required that we can't fetch, you must include it with the Event's supplemental_data section.

For example, if you're submitting a login event and plan on running LexisNexis ThreatMetrix in one of your workflows, you should explicitly specify the threatmetrix_session_id within the supplemental_data{}object in your request:

{
  "event_type": "login",
  "data": {
    "supplemental_data": {
   	 "threatmetrix_session_id": "foo"
  }
}

The fields required in supplemental_data are based on the Source Workflows/Journey mapped for the Event Type and will be dynamic. You can check which fields are needed by calling the /events/schema API.

Entity Data Hydration

When you specify an Entity using the entity_token or external_entity_id fields, Alloy will automatically fetch and hydrate previously supplied data and make it available on the request payload (when appropriate). If you supply a field explicitly in your payload, this will take priority over Alloy's hydration behavior for that field when sending data to downstream vendors or executing other policy logic.

This behavior allows you to use other data that Alloy has on file for a given Entity for decisioning purposes without requiring you to send it again explicitly in your request payload.

Alloy also supports hydration of Bank Account data on transaction type events, based on the account specified in the external_account_id field.

Source Workflow Impact on Entity Fields

❗️

Source Workflow Impact on Entity Fields

Although most Event Types already require specifying either the external_entity_id or entity_token field in the request payload, this field is optional by default for Bank Account and External Account create/update events, since Entities are either specified via the entities[] field instead to support many-to-many relationships (or in the case of update events, may not be changing during the update).

However, if an Event Type is mapped to a Source Workflow, the top-level entity field will become required. To future-proof your integration for new use cases, we recommend including the top-level Entity field in your Bank Account events even when it is not required. Including the top level field will not impact the Entities attached to the Account record via entities[], and is only used so that Alloy knows which Entity to attach the Source Workflow evaluation to and use for PII hydration.