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`

A legal entity created with one of these values also opens a compliance case with two pending requested actions, and you will receive a case.opened Case webhook. See step 3 to resolve it.

Type	Requested action categories
`individual`	`onboarding.ssn_check_failure`, `onboarding.proof_of_address_failure`
`business`	`onboarding.tin_check_failure`, `onboarding.business_registry_verification_failure`

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

3. Simulate compliance case resolution

A pending legal entity created with the date values above has an open compliance case. Get the case id from the case.opened webhook, or list cases with subject_id set to the legal entity ID. Then resolve the case with the case resolution simulation endpoint:

curl --request PATCH \
  -u ORGANIZATION_ID:API_KEY \
  --url https://app.moderntreasury.com/api/simulations/cases/{id}/resolve \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "onboarding.proof_of_address_failure"
  }'

With category, only that requested action is resolved. You will receive case.updated while other actions are still pending, and case.resolved when the last action is resolved.
Without a request body, the whole case is resolved and you will receive case.resolved.

The case resolution simulation request is async -- listen for Case webhooks. Resolving the case does not change the legal entity's status. Use the legal entity status simulation in step 2 for that. Transitioning the legal entity to active or denied also resolves its open case.