> ## 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.

# Getting started with CRM

> Follow this guide to register Holders in CRM and link them to ledger accounts with Instruments through the Midaz REST API.

This guide shows how to create and manage **Holders** — the customers or companies behind your accounts.

It also links each holder to a ledger account with an **Instrument**. By the end, you have a holder registered in CRM and linked to a ledger account.

## Prerequisites

***

Before you begin, make sure you meet the following requirements:

* You completed the [Midaz setup](/en/midaz/midaz-setup) guide and all services run.
* At least one **Organization**, **Ledger**, and **Account** already exist, as created in the [Midaz Getting Started](/en/midaz/midaz-getting-started) guide.
* The Midaz ledger serves the holder and instrument endpoints. In Midaz v4, CRM is part of the ledger binary, so it needs no separate service or port.

<Note>
  Replace the placeholder IDs in the examples below with the real IDs from your environment.
</Note>

## CRM components

***

The CRM (Customer Relationship Management) component lets you register the people and companies behind your ledger accounts.

It manages two core entities:

* **Holders**: Individuals (`NATURAL_PERSON`) or companies (`LEGAL_PERSON`) that own accounts.
* **Instruments**: The link between a holder and a specific ledger account, with optional banking details.

This model lets one holder own many accounts across different ledgers. It keeps identity and contact information in one place.

## Step 1 — Create a holder

***

A **Holder** represents a person or company in your system. Create holders for individuals (`NATURAL_PERSON`) or companies (`LEGAL_PERSON`).

Send a `POST` request with the holder's type, name, document, contact, and address. For the full request and response schema, see [Create a holder](/en/reference/midaz/create-a-holder).

<Accordion title="Individual holder example">
  ```bash theme={null}
  curl -X POST http://localhost:3002/v1/organizations/{organization_id}/holders \
    -H "Content-Type: application/json" \
    -d '{
      "type": "NATURAL_PERSON",
      "name": "Jane Smith",
      "document": "12345678900",
      "contact": {
        "primaryEmail": "jane.smith@example.com",
        "mobilePhone": "+15551234567"
      },
      "addresses": {
        "primary": {
          "line1": "123 Main Street",
          "line2": "Apt 4B",
          "city": "New York",
          "state": "NY",
          "zipCode": "10001",
          "country": "US",
          "description": "Home address"
        }
      },
      "naturalPerson": {
        "favoriteName": "Jane",
        "birthDate": "1990-05-15",
        "nationality": "American"
      },
      "metadata": {
        "segment": "premium",
        "source": "onboarding"
      }
    }'
  ```
</Accordion>

<Accordion title="Company holder example">
  To register a company instead of an individual, set the type to `LEGAL_PERSON`:

  ```bash theme={null}
  curl -X POST http://localhost:3002/v1/organizations/{organization_id}/holders \
    -H "Content-Type: application/json" \
    -d '{
      "type": "LEGAL_PERSON",
      "name": "Acme Corp Ltd",
      "document": "12345678000199",
      "contact": {
        "primaryEmail": "finance@acmecorp.com",
        "mobilePhone": "+15559876543"
      },
      "legalPerson": {
        "tradeName": "Acme Corp",
        "activity": "Financial services",
        "type": "Limited Liability",
        "foundingDate": "2015-03-20",
        "size": "Medium",
        "status": "Active",
        "representative": {
          "name": "Bob Johnson",
          "document": "98765432100",
          "email": "bob@acmecorp.com",
          "role": "CFO"
        }
      }
    }'
  ```
</Accordion>

<Tip>
  Save the `holderId` from the response. You use it when you create instruments.
</Tip>

## Step 2 — Link a holder to an account

***

Once the holder exists, link it to a ledger account with an **Instrument**. An instrument connects a holder to one account inside a ledger, with optional banking details.

For the full request and response schema, see [Create an instrument](/en/reference/midaz/create-an-instrument).

<Accordion title="Example request">
  ```bash theme={null}
  curl -X POST http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}/instruments \
    -H "Content-Type: application/json" \
    -d '{
      "ledgerId": "{ledger_id}",
      "accountId": "{account_id}",
      "bankingDetails": {
        "branch": "0001",
        "account": "123450",
        "type": "CACC",
        "openingDate": "2025-01-15",
        "countryCode": "US",
        "bankId": "12345"
      },
      "metadata": {
        "isPrimary": "true"
      }
    }'
  ```
</Accordion>

## Step 3 — Query and update your data

***

Once holders and instruments exist, you can retrieve, list, and update them.

| Operation                      | Endpoint                                                                                  | API reference                                                        |
| ------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Retrieve a holder              | `GET /v1/organizations/{organization_id}/holders/{holder_id}`                             | [Retrieve a holder](/en/reference/midaz/retrieve-a-holder)           |
| List all holders               | `GET /v1/organizations/{organization_id}/holders?limit=10&page=1`                         | [List holders](/en/reference/midaz/list-holders)                     |
| List instruments for a holder  | `GET /v1/organizations/{organization_id}/instruments?holder_id={holder_id}`               | [List instruments](/en/reference/midaz/list-instruments)             |
| Retrieve a specific instrument | `GET /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Retrieve an instrument](/en/reference/midaz/retrieve-an-instrument) |
| Update a holder                | `PATCH /v1/organizations/{organization_id}/holders/{holder_id}`                           | [Update a holder](/en/reference/midaz/update-a-holder)               |

<Accordion title="Update holder example">
  ```bash theme={null}
  curl -X PATCH http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id} \
    -H "Content-Type: application/json" \
    -d '{
      "contact": {
        "primaryEmail": "jane.new-email@example.com",
        "mobilePhone": "+15559999999"
      },
      "metadata": {
        "segment": "vip",
        "source": "onboarding"
      }
    }'
  ```
</Accordion>

<Note>
  The update changes only the fields you send. All other fields stay unchanged.
</Note>

## Step 4 — Clean up

***

To remove resources, delete instruments first, then holders.

| Operation            | Endpoint                                                                                     | API reference                                                    |
| -------------------- | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Delete an instrument | `DELETE /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}` | [Delete an instrument](/en/reference/midaz/delete-an-instrument) |
| Delete a holder      | `DELETE /v1/organizations/{organization_id}/holders/{holder_id}`                             | [Delete a holder](/en/reference/midaz/delete-a-holder)           |

<Accordion title="Example requests">
  Delete an instrument:

  ```bash theme={null}
  curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}
  ```

  Delete a holder:

  ```bash theme={null}
  curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}
  ```
</Accordion>

## Summary

***

In this guide, you:

1. Created a **Holder** to register an individual or company in CRM.
2. Created an **Instrument** to link the holder to a ledger account.
3. Queried and updated CRM data.
4. Removed instruments and holders when no longer needed.

## Next steps

***

<CardGroup cols={2}>
  <Card title="CRM API reference" icon="code" href="/en/reference/midaz/create-a-holder">
    Explore advanced filtering, metadata queries, and all available endpoints.
  </Card>

  <Card title="Using CRM with Midaz Console" icon="desktop" href="/en/midaz/crm/using-crm-with-midaz-console">
    Manage holders through a graphical interface.
  </Card>
</CardGroup>