Guides
  1. Journeys
  2. What are Journeys?

Multi-Entity Applications

A single Journey Application can include multiple entities — for example, a business and its beneficial owners. Each entity is evaluated independently, and the top-level Journey Application status reflects a hierarchy across all of them. Multi-entity support is one of the most powerful features of Journeys, but it changes how your integration should read responses.


Core concepts

  • Entity Application - The evaluation record for a single entity within a Journey Application. Identified by entity_application_token.
  • Top-level status - The Journey Application's status, derived from a hierarchy across all Entity Application statuses.

How it works

When you submit an API request with multiple entities, Alloy creates one Journey Application and then attaches one Entity Application per entity. Each Entity Application is evaluated independently — some may complete instantly, while others may wait on Step-Up or Manual Review.

The per-entity statuses live in the API response field _embedded.entity_applications[].entity_application_status. See the API reference for more details.

The Journey Application's top-level status is derived from a hierarchy across all entity statuses. For example, if any entity is in pending_step_up, the top-level status will also be pending_step_up, even if other entities have already completed.

See an entire breakdown of the Journey Application status hierarchy here.


When to use it

Multi-entity Journey Applications are required for any use case where multiple parties need to be evaluated together. This is most commonly for KYB (business + beneficial owners) and joint accounts.

Even if your current use case is single-entity, Alloy recommends building your integration to read from _embedded.entity_applications[] so that adding multi-entity support later doesn't require changes to your integration.


How it fits in Alloy

Multi-entity is a property of the Journey Application object — there's no separate API or endpoint. The same Create / Update / Rerun endpoints handle both single- and multi-entity cases.