> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a holder and open an account (API)

> Register the person or company that owns an account in the CRM of Midaz, then open the account for that holder, through the Midaz API.

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](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact.md).
* Your system has a token that can create holders and accounts in Midaz.

## Diagram

***

![Register a holder and open an account](https://mintcdn.com/lerian-49cb71fc/KypD0TIKUCqZ014J/images/en/d2/id-midaz-register-a-holder.svg?fit=max\&auto=format\&n=KypD0TIKUCqZ014J\&q=85\&s=20567a65b94a77ef4b02ca626a15d71a)

## Steps through the API

***

| # | From | To | Message | Lerian API | What happens |
| - | - | - | - | - | - |
| 1 | Your institution | Midaz | API call | [`POST /v2/organizations/{organization_id}/holders`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-holder) | 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/create-holder-account) | 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`](https://docs.lerian.studio/en/reference/products/midaz/v2/list-accounts-by-holder) | 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](https://docs.lerian.studio/en/reference/products/midaz/v2/create-instrument.md). |
| 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. |

## Related

***

* [Set up a ledger and post the first transaction](https://docs.lerian.studio/en/diagrams/lerian-products/midaz-create-and-transact.md)
* [Holders](https://docs.lerian.studio/en/products/midaz/crm/holders.md)
* [Instruments](https://docs.lerian.studio/en/products/midaz/crm/alias-accounts.md)
* [Midaz error list](https://docs.lerian.studio/en/reference/products/midaz/error-list.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.