Simulate Legal Entity Status Transitions

Overview

In the sandbox, you can simulate scenarios where your legal entity transitions to a status outside of active. This is useful for ensuring that your integration properly handles the various states. This guide walks you through how to simulate these events so you can build the end-to-end experience in your application.

Legal Entity Statuses

Status	Description
`pending`	Initial status upon creation. The legal entity is awaiting KYC/KYB verification and cannot yet transact.
`active`	The legal entity has passed compliance verification and is approved to transact.
`suspended`	The legal entity has been temporarily suspended from transacting, e.g. due to a compliance investigation.
`denied`	The legal entity has been denied as a result of failing compliance verification.

1. Create a legal entity

The first step is to create a legal entity. Legal entities in Sandbox are auto-activated by default, meaning that they will automatically transition from pending to active after creation. In order to keep a Sandbox legal entity in pending (e.g. in order to test a legal entity transitioning from pending to denied) utilize the following date values when creating an individual or business legal entity:

Type	Paramater	Value
`individual`	`date_of_birth`	`1900-01-01`
`business`	`date_formed`	`1900-01-01`

For more information on creating legal entities refer to our guides for onboarding an individual and onboarding a business.

2. Simulate legal entity status changes

Once you have a Sandbox legal entity to work with, you can now simulate status changes via the simulation endpoint. See below for an example request:

curl --request PATCH \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/simulations/legal_entities/{id}/update_status \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "suspended"
  }'

The legal entity simulation request is async -- listen for Legal Entity webhooks related to the status you've transitioned to.

📘
Note: Legal entity status simulations are only available for valid status transitions. See below for a diagram of valid transitions.

flowchart LR 
pending --> active & denied
active --> suspended
suspended --> active