> ## 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
> Create Holders and link them to Ledger Accounts via Aliases — register customers and companies behind your Midaz Accounts.
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](/en/midaz/midaz-setup) guide and all services are running.
* At least one **Organization**, **Ledger**, and **Account** already exist (as created in the [Midaz Getting Started](/en/midaz/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](/en/reference/midaz/crm/create-holder).
```bash theme={null}
curl -X POST http://localhost:4003/v1/holders \
-H "Content-Type: application/json" \
-H "X-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`:
```bash theme={null}
curl -X POST http://localhost:4003/v1/holders \
-H "Content-Type: application/json" \
-H "X-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.
## Step 2 — Link a holder to an account
***
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](/en/reference/midaz/crm/create-alias-account).
```bash theme={null}
curl -X POST http://localhost:4003/v1/holders//aliases \
-H "Content-Type: application/json" \
-H "X-Organization-Id: " \
-d '{
"ledgerId": "",
"accountId": "",
"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.
| Operation | Endpoint | API reference |
| ------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------- |
| Retrieve a holder | `GET /v1/holders/` | [Retrieve a holder](/en/reference/midaz/crm/retrieve-holder) |
| List all holders | `GET /v1/holders?limit=10&page=1` | [List holders](/en/reference/midaz/crm/list-holders) |
| List aliases for a holder | `GET /v1/aliases?holder_id=` | [List alias accounts](/en/reference/midaz/crm/list-alias-accounts) |
| Retrieve a specific alias | `GET /v1/holders//aliases/` | [Retrieve an alias account](/en/reference/midaz/crm/retrieve-alias-account) |
| Update a holder | `PATCH /v1/holders/` | [Update a holder](/en/reference/midaz/crm/update-holder) |
```bash theme={null}
curl -X PATCH http://localhost:4003/v1/holders/ \
-H "Content-Type: application/json" \
-H "X-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.
| Operation | Endpoint | API reference |
| --------------- | --------------------------------------------------- | ----------------------------------------------------------------------- |
| Delete an alias | `DELETE /v1/holders//aliases/` | [Delete an alias account](/en/reference/midaz/crm/delete-alias-account) |
| Delete a holder | `DELETE /v1/holders/` | [Delete a holder](/en/reference/midaz/crm/delete-holder) |
Delete an alias:
```bash theme={null}
curl -X DELETE http://localhost:4003/v1/holders//aliases/ \
-H "X-Organization-Id: "
```
Delete a holder:
```bash theme={null}
curl -X DELETE http://localhost:4003/v1/holders/ \
-H "X-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
***
Explore advanced filtering, metadata queries, and all available endpoints.
Manage holders through a graphical interface.