Skip to main content
This guide shows how to create and manage Holders (customers or companies) and link them to ledger accounts using Aliases. By the end of this guide, you will have a holder registered in CRM and connected to an existing account in your Midaz ledger.

​
Prerequisites

Before you begin, make sure the following requirements are met:
  • You have completed the Midaz setup guide and all services are running.
  • At least one Organization, Ledger, and Account already exist (as created in the Midaz Getting Started guide).
  • The CRM service is running on port 4003 (started automatically with make up).
In the examples below, replace the placeholder UUIDs with the actual 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.
  • Aliases: The link between a holder and a specific ledger account, with optional banking details.
This model allows a single holder to own multiple accounts across different ledgers while keeping identity and contact information centralized.

​
Step 1 — Create a holder

A Holder represents a person or company in your system. You can create holders for individuals (NATURAL_PERSON) or companies (LEGAL_PERSON). Send a POST request with the holder’s type, name, document, contact information, and address. For the full request and response schema, see Create a holder. 
curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -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"
    }
  }'
To register a company instead of an individual, set the type to LEGAL_PERSON:
curl -X POST http://localhost:4003/v1/holders \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -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 returned in the response. You will use it when creating aliases.
Once the holder exists, link it to a ledger account by creating an Alias. An alias connects a holder to a specific account inside a ledger, with optional banking details. For the full request and response schema, see Create an alias account. 
curl -X POST http://localhost:4003/v1/holders/<holder-id>/aliases \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -d '{
    "ledgerId": "<your-ledger-id>",
    "accountId": "<your-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 aliases are created, you can retrieve, list, and update them.
OperationEndpointAPI reference
Retrieve a holderGET /v1/holders/<holder-id>Retrieve a holder
List all holdersGET /v1/holders?limit=10&page=1List holders
List aliases for a holderGET /v1/aliases?holder_id=<holder-id>List alias accounts
Retrieve a specific aliasGET /v1/holders/<holder-id>/aliases/<alias-id>Retrieve an alias account
Update a holderPATCH /v1/holders/<holder-id>Update a holder
curl -X PATCH http://localhost:4003/v1/holders/<holder-id> \
  -H "Content-Type: application/json" \
  -H "X-Organization-Id: <your-organization-id>" \
  -d '{
    "contact": {
      "primaryEmail": "jane.new-email@example.com",
      "mobilePhone": "+15559999999"
    },
    "metadata": {
      "segment": "vip",
      "source": "onboarding"
    }
  }'
Only the fields included in the request body are updated. All other fields remain unchanged.

​
Step 4 — Clean up

To remove resources, delete aliases first, then holders.
OperationEndpointAPI reference
Delete an aliasDELETE /v1/holders/<holder-id>/aliases/<alias-id>Delete an alias account
Delete a holderDELETE /v1/holders/<holder-id>Delete a holder
Delete an alias:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id>/aliases/<alias-id> \
  -H "X-Organization-Id: <your-organization-id>"
Delete a holder:
curl -X DELETE http://localhost:4003/v1/holders/<holder-id> \
  -H "X-Organization-Id: <your-organization-id>"

​
Summary

In this guide, you:
  1. Created a Holder to register an individual or company in CRM.
  2. Created an Alias to link the holder to a ledger account.
  3. Queried and updated CRM data.
  4. Removed aliases 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.