Getting started with CRM

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 guide and all services run.
At least one Organization, Ledger, and Account already exist, as created in the 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.

Replace the placeholder IDs in the examples below with the real IDs from your environment.

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.

Individual holder example

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"
    }
  }'

Company holder example

To register a company instead of an individual, set the type to LEGAL_PERSON:

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"
      }
    }
  }'

Save the holderId from the response. You use it when you create instruments.

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.

Example request

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"
    }
  }'

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
List all holders	`GET /v1/organizations/{organization_id}/holders?limit=10&page=1`	List holders
List instruments for a holder	`GET /v1/organizations/{organization_id}/instruments?holder_id={holder_id}`	List instruments
Retrieve a specific instrument	`GET /v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}`	Retrieve an instrument
Update a holder	`PATCH /v1/organizations/{organization_id}/holders/{holder_id}`	Update a holder

Update holder example

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"
    }
  }'

The update changes only the fields you send. All other fields stay unchanged.

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
Delete a holder	`DELETE /v1/organizations/{organization_id}/holders/{holder_id}`	Delete a holder

Example requests

Delete an instrument:

curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}/instruments/{instrument_id}

Delete a holder:

curl -X DELETE http://localhost:3002/v1/organizations/{organization_id}/holders/{holder_id}

Summary

In this guide, you:

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

Next steps

CRM API reference

Explore advanced filtering, metadata queries, and all available endpoints.

Using CRM with Midaz Console

Manage holders through a graphical interface.

Midaz Core

CRM

Fees

Getting started with CRM

Prerequisites

CRM components

Step 1 — Create a holder

Step 2 — Link a holder to an account

Step 3 — Query and update your data

Step 4 — Clean up

Summary

Next steps

CRM API reference

Using CRM with Midaz Console

​Prerequisites

​CRM components

​Step 1 — Create a holder

​Step 2 — Link a holder to an account

​Step 3 — Query and update your data

​Step 4 — Clean up

​Summary

​Next steps

CRM API reference

Using CRM with Midaz Console

Prerequisites

CRM components

Step 1 — Create a holder

Step 2 — Link a holder to an account

Step 3 — Query and update your data

Step 4 — Clean up

Summary

Next steps