Register a holder and open an account (API) - Lerian

Register the holder of an account, the person or company that owns it, and open the account for that holder.

Participants

Your institution. Your system. It registers the holder and opens the account.
Midaz. The ledger and its CRM. It keeps the holder, the account and the instrument that links them.

Before you start

The organization, the ledger and the asset exist. See Set up a ledger and post the first transaction.
Your system has a token that can create holders and accounts in Midaz.

Diagram

Register a holder and open an account

Steps through the API

#	From	To	Message	Lerian API	What happens
1	Your institution	Midaz	API call	`POST /v2/organizations/{organization_id}/holders`	Register the holder with its `type` (`NATURAL_PERSON` or `LEGAL_PERSON`), `name` and `document`.
2	Midaz	Your institution	API answer		Midaz answers `201` with the holder `id`.
3	Your institution	Midaz	API call	`POST /v2/organizations/{organization_id}/ledgers/{ledger_id}/holders/{holder_id}/accounts`	Open the account for the holder. Send the account fields, such as `assetCode`, `type` and `alias`. To create the instrument too, add `bankingDetails`, `regulatoryFields` or `relatedParties`. Send the `X-Idempotency` header.
4	Midaz	Midaz	Internal step		Midaz creates the account and its `default` balance. The holder in the path owns the account.
5	Midaz	Midaz	Internal step		When the request has instrument fields, Midaz creates the instrument that links the holder to the account.
6	Midaz	Your institution	API answer		Midaz answers `201` with the `account` and the `instrument`.
7	Your institution	Midaz	API call	`GET /v2/organizations/{organization_id}/holders/{holder_id}/accounts`	List the accounts of the holder.
8	Midaz	Your institution	API answer		Midaz returns the accounts that the holder owns.

How you know it finished

The list of the accounts of the holder shows the new account.

What can go wrong

Situation	What you see	What to do
The account was created, but the instrument was not	`201` with `instrument` as `null` and an `instrumentError`	The account exists and works. Create the instrument with Create an instrument.
The holder does not exist, and the ledger requires a holder	`404` with `CRM-0006`	Register the holder first.
You open an account without a holder, and the ledger requires one	`422` with `0491`	Open the account for a holder, as in step 3.
The answer to step 3 does not arrive	No answer, or a timeout	Within the time in the `X-TTL` header (300 seconds by default), send the same request with the same `X-Idempotency` key. A replay returns the first answer with `X-Idempotency-Replayed: true`. After a `409` with `0084`, or after that time, list the accounts of the holder before you try again.