# Customer Management Tutorial
## Customer Management
Take a look at the relationships between objects in the Customer Management Service and other resources in the Emporix Commerce Engine. Click the diagram to enlarge it.
## How to set up business customer information
Setting up a business customer's information is a process made up of two steps:
1. [Adding a location](#add-a-location)
2. [Adding a legal entity](#add-a-legal-entity)
### Before you start
Make sure you have marked the country in which the company operates as **active**. You can do it by sending a request to the [Updating a country](https://developer.emporix.io/api-references/api-guides/configuration/country-service/api-reference/countries#patch-country-tenant-countries-countrycode) endpoint in the Emporix API Country Service.
### Add a location
A location is a physical address where a company operates, such as its headquarters, office, or warehouse. To add a new location, send a request to the [Creating a new location](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/locations#post-tenant-locations) endpoint.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X POST
'https://api.emporix.io/customer-management/{tenant}/locations'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'Content-Type: application/json'
-d '{
"name": "Main HQ",
"type": "HEADQUARTER",
"contactDetails": {
"emails": [
"jon.doe@example.com",
"adam.smith@sample.org"
],
"phones": [
"1234567890",
"123456789"
],
"addressLine1": "W Sample St",
"addressLine2": "3601-3799",
"city": "South Bend",
"state": "Indiana",
"postcode": "46619",
"countryCode": "US",
"tags": [
"shipping"
]
}
}'
```
{% hint style="warning" %}
The `id` from the response is further referred to as `locationId`.
{% endhint %}
### Add a legal entity
A legal entity is a representation of a company. To add a new legal entity, send a request to the [Creating a legal entity](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/legal-entities#post-tenant-legal-entities) endpoint.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X POST
'https://api.emporix.io/customer-management/{tenant}/legal-entities'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'Content-Type: application/json'
-d '{
"name": "ABC Company",
"type": "COMPANY",
"legalInfo": {
"legalName": "ABC Company",
"registrationDate": "2022-03-31T13:18:02.379Z",
"registrationAgency": "Comp reg agency",
"registrationId": "627e06ecf0452c2d6c0b81391",
"countryOfRegistration": "DE",
"taxRegistrationNumber": "1234"
},
"accountLimit": {
"currency": "EUR",
"value": 1000.99
},
"customerGroups": [
{
"id": "123e06ecf0452c2d6c0b81390",
"name": {
"en": "En customer group name",
"de": "De customer group name"
}
}
],
"entitiesAddresses": [
{
"id": "123e123455452c2d6c0b81390"
},
{
"id": "123e06ecf0acd223140b12345"
}
],
"approvalGroup": [
{
"id": "123e121111452c12330b81390"
},
{
"id": "123e061110acd223133333345"
}
]
}'
```
## How to add a subsidiary
Subsidiaries are companies legally owned or controlled by other companies. In the Emporix Commerce Engine, subsidiaries are structured the same way as regular companies — the only difference is that a subsidiary must have its parent company specified.
### Before you start
Make sure you have already finished the [How to set up business customer information](#how-to-set-up-business-customer-information) tutorial.
### Retrieve the ID of the parent company
To find out what a company ID is, send a request to the [Retrieving all legal entities](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/legal-entities#get-tenant-legal-entities) endpoint and use the `q` query parameter to find the desired company.
{% hint style="warning" %}
The `id` from the response is further referred to as `parentId`.
{% endhint %}
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X GET
'https://api.emporix.io/customer-management/{tenant}/legal-entities?pageNumber=1&pageSize=16&sort=name%2Cmetadata.createdAt%3Adesc&q=name%3A~john&fields=name%2Ctype&id=string&name=string&type=COMPANY&parentId=string&legalInfo.legalName=string&legalInfo.registrationDate=string&legalInfo.taxRegistrationNumber=string&legalInfo.registrationAgency=string&legalInfo.countryOfRegistration=string&legalInfo.registrationId=string'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'X-Total-Count: false'
```
### Add a subsidiary
Subsidiaries are added similarly to their parent companies. To add a new subsidiary, send a request to the [Creating a new legal entity](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/legal-entities#post-tenant-legal-entities) endpoint. In the request body, set the `type` field to `SUBSIDIARY` and provide the `parentId`.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X POST
'https://api.emporix.io/customer-management/{tenant}/legal-entities'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'Content-Type: application/json'
-d '{
"name": "ABC Subsidiary",
"type": "SUBSIDIARY",
"legalInfo": {
"legalName": "ABC Subsidiary",
"registrationDate": "2022-03-31T13:18:02.379Z",
"registrationAgency": "Comp reg agency",
"registrationId": "627e06ecf0452c2d6c0b81391",
"countryOfRegistration": "DE",
"taxRegistrationNumber": "1234"
},
"accountLimit": {
"currency": "EUR",
"value": 1000.99
},
"customerGroups": [
{
"id": "123e06ecf0452c2d6c0b81390",
"name": {
"en": "En customer group name",
"de": "De customer group name"
}
}
],
"entitiesAddresses": [
{
"id": "123e123455452c2d6c0b81390"
},
{
"id": "123e06ecf0acd223140b12345"
}
],
"approvalGroup": [
{
"id": "123e121111452c12330b81390"
},
{
"id": "123e061110acd223133333345"
}
]
}'
```
## How to add an employee to a company customer group
You can offer personalized pricing to your business customers' employees by adding them to company customer groups. A company customer group is automatically created when that company data is added to the system.
{% hint style="warning" %}
When added to a subsidiary customer group, the employee is also automatically assigned to customer groups of all the subsidiary parent companies.
{% endhint %}
### Before you start
Make sure the following requirements are fulfilled:
* You have already finished the [How to set up business customer information](#how-to-set-up-business-customer-information) tutorial.
* The employee has their customer account set up.
{% hint style="warning" %}
A customer account can be created by the employee themselves or from your Emporix tenant's side. For more information, check out the following endpoints in the Emporix API Reference:
* [Creating a new customer (customer-managed)](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-management/api-reference/authentication-and-authorization#post-customer-tenant-signup)
* [Creating a new customer (tenant-managed)](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-service/api-reference/account-and-profile#post-customer-tenant-customers)
{% endhint %}
### Retrieve the ID of the company
To find out what a company ID is, send a request to the [Retrieving all legal entities](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/legal-entities) endpoint and use the `q` query parameter to find the desired company.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X GET
'https://api.emporix.io/customer-management/{tenant}/legal-entities?pageNumber=1&pageSize=16&sort=name%2Cmetadata.createdAt%3Adesc&q=name%3A~john&fields=name%2Ctype&id=string&name=string&type=COMPANY&parentId=string&legalInfo.legalName=string&legalInfo.registrationDate=string&legalInfo.taxRegistrationNumber=string&legalInfo.registrationAgency=string&legalInfo.countryOfRegistration=string&legalInfo.registrationId=string'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'X-Total-Count: false'
```
{% hint style="warning" %}
The `id` from the response is further referred to as `legalEntityId`.
{% endhint %}
### Retrieve the employee's customer ID
To retrieve an employee's customer ID, send a request to the [Retrieving a list of customers](https://developer.emporix.io/api-references/api-guides/companies-and-customers/customer-service/api-reference/account-and-profile) endpoint and use the `q` query parameter. For example, you can search for a customer with a specific email address with `q=contactEmail:employeeEmail`.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/DlWL3YvOW1OCA6f0AqfJ" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-service/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X GET
'https://api.emporix.io/customer/{tenant}/customers?q=contactEmail%3A{email}&sort=string&pageNumber=1&pageSize=60&expand=string'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
```
{% hint style="warning" %}
The `id` from the response is further referred to as `customerId`.
{% endhint %}
### Assign the contact to the company
A contact represents an employee of one or more business customers. To assign a contact to a legal entity (in this case, the desired company), send a request to the [Creating a new contact assignment](https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/api-reference/contact-assignments#post-tenant-contact-assignments) endpoint and provide `legalEntityId` and `customerId` in the request body.
{% hint style="success" %}
To test the endpoint, open the API reference or check the example of a curl request.
{% endhint %}
{% content-ref url="/pages/goJs2tqKAOpS2eob16wf" %}
[API Reference](/api-references/api-guides/companies-and-customers/customer-management/api-reference.md)
{% endcontent-ref %}
```bash
curl -i -X POST
'https://api.emporix.io/customer-management/{tenant}/contact-assignments'
-H 'Authorization: Bearer {{OAUTH2_ACCESS_TOKEN}}'
-H 'Content-Type: application/json'
-d '{
"legalEntity": {
"id": "612306ecf0452c2d6c0b81392"
},
"customer": {
"id": "612306ecf0452c2d6c0b81123"
},
"type": "BILLING",
"primary": true
}'
```
Once desired employees are added to appropriate customer groups, you can — for example — create personalized price lists for them. For instructions, check out [*How to configure a price list*](/api-references/api-guides/prices-and-taxes/price-service/price.md#how-to-configure-a-price-list) in the *Price Service guide*.
## Customer assignment rules
Emporix platform enforces rules when assigning customers to predefined groups to ensure role assignments remain valid and avoid conflicts. Within a single company, a user can belong to only one predefined group. Validation applies within the scope of a single company (legal entity) only. It does not extend across different companies or any subsidiaries.
Examples:
* If a customer is already assigned to one predefined group (for example, Emporix Admin Group), then it's not possible to assign that same customer to another predefined group within the same company.
* If a customer is assigned to an *Admin* group in one company (for example, Company A), then the same customer may also be assigned to an *Admin* group in another company (for example, Company B).
* If a customer is assigned to an *Admin* group in a parent company (for example, Company A), then that same customer may also be assigned to another role such as *Buyer* in the parent company’s subsidiary.
{% hint style="success" %}
The exception is the *Contact* group, which can always be assigned.
{% endhint %}
### Company Contact Propagation
As a part of the group assignment you can decide how the contact assignments are shared within a company hierarchy. You can choose from the following options:
* **UPWARD**: Contacts assigned to a subsidiary are also visible at the parent company level. This is a default setting.
* **DOWNWARD**: Contacts assigned to a parent company are also visible in all subsidiaries.
* **DISABLED**: Contacts remain only in the company where they were assigned, with no propagation.
Propagation happens only at the moment of assignment - creating the contact in the selected company also creates corresponding contacts in related companies according to the chosen direction.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developer.emporix.io/api-references/api-guides/companies-and-customers/client-management/customer-management.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.