## Map a provider's customer to a customer address (tenant:trade:msp:write)

`PUT /api/trade/v1/msp/mappings/customers`

Module: Trade · operationId: `saveMspCustomerMapping` · Tag: MSP billing · Auth: access token (`Authorization: Bearer <accessToken>`)

Creates or replaces the mapping of provider and provider customer. Drafts become stale.

### Request body

`application/json` (required)

- `addressId` (string (uuid), required): Masterdata address that is billed.
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceCustomer` (string, required): The provider's customer (id or name). (max length 200)
- `addressName` (string): Name of the masterdata address. (max length 300)
- `adrNr` (string): Adressnummer of the masterdata address. Optional in a PUT (taken from the address the person picked); without it a save to the same address keeps the stored number, a save to another address clears it. AutoMap fills it from masterdata's match. (max length 64)
- `contractId` (string (uuid)): Contract the usage belongs to (its usage positions set prices).
- `customerNumber` (string): Kundennummer of the masterdata address, the number providers send (Sophos `assignedAccountIdentifier` "11141 | Name", MailStore instance id "k11141"). Optional in a PUT, same rules as `adrNr`. (max length 64)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping or a suggestion (`adrNr`: an Ingram end customer whose Custom_Account_ID is our address number). `created`: only on mappings of earlier versions, which created the masterdata address of an Ingram end customer by themselves. (one of `adrNr`, `customerNumber+address`, `customerNumber`, `name+address`, `name`, `address`, `created`)
- `source` (string, read-only): `auto`: masterdata has the provider's customer number as an address's customer number, billed like a manual mapping. `suggested`: found by name or postal address only, assigns nothing and bills nothing until it is saved. Every save through the API is manual, also the save of an automatic mapping or a suggestion. (one of `manual`, `auto`, `suggested`)
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example:

```json
{
  "addressId": "3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10",
  "addressName": "Muster GmbH",
  "provider": "sophos",
  "sourceCustomer": "5b1d6a0e-2f4c-4d1b-9a3e-7c8f0e1d2a3b"
}
```

### Responses

- **200** Saved (`application/json`)
- **400** Error (`application/json`)
- **401** No valid session or bearer token (no body).
- **403** Missing permission, no active tenant in the token, or a missing CSRF token on a cookie write. (`application/json`)
- **404** Not found in the tenant. (`application/json`)

Fields of the 200 answer:

- `addressId` (string (uuid), required): Masterdata address that is billed.
- `provider` (string, required): MSP provider (`mailstore`, `sophos`, `ingram`, `itc`, …). (max length 32)
- `sourceCustomer` (string, required): The provider's customer (id or name). (max length 200)
- `addressName` (string): Name of the masterdata address. (max length 300)
- `adrNr` (string): Adressnummer of the masterdata address. Optional in a PUT (taken from the address the person picked); without it a save to the same address keeps the stored number, a save to another address clears it. AutoMap fills it from masterdata's match. (max length 64)
- `contractId` (string (uuid)): Contract the usage belongs to (its usage positions set prices).
- `customerNumber` (string): Kundennummer of the masterdata address, the number providers send (Sophos `assignedAccountIdentifier` "11141 | Name", MailStore instance id "k11141"). Optional in a PUT, same rules as `adrNr`. (max length 64)
- `id` (string (uuid), read-only): Id of the mapping.
- `matchedBy` (string, read-only): Rule of an automatic mapping or a suggestion (`adrNr`: an Ingram end customer whose Custom_Account_ID is our address number). `created`: only on mappings of earlier versions, which created the masterdata address of an Ingram end customer by themselves. (one of `adrNr`, `customerNumber+address`, `customerNumber`, `name+address`, `name`, `address`, `created`)
- `source` (string, read-only): `auto`: masterdata has the provider's customer number as an address's customer number, billed like a manual mapping. `suggested`: found by name or postal address only, assigns nothing and bills nothing until it is saved. Every save through the API is manual, also the save of an automatic mapping or a suggestion. (one of `manual`, `auto`, `suggested`)
- `updatedAt` (string (date-time), read-only): When the mapping was last saved.

Example 200 answer:

```json
{
  "addressId": "3c5e7a91-2b4d-4f6a-8c1e-5d7f9a0b1c03",
  "addressName": "Bäckerei Sonnleitner GmbH",
  "adrNr": "20003",
  "customerNumber": "10003",
  "id": "3b4c5d6e-7f8a-4b9c-8d0e-1f2a3b4c5d03",
  "provider": "sophos",
  "source": "manual",
  "sourceCustomer": "6f1e2d3c-4b5a-4968-8776-a5b4c3d2e1f0",
  "updatedAt": "2026-11-19T10:40:00Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/trade/v1/msp/mappings/customers' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3f8a2c1e-5b7d-4e9f-a1c3-0d2e4f6a8b10","addressName":"Muster GmbH","provider":"sophos","sourceCustomer":"5b1d6a0e-2f4c-4d1b-9a3e-7c8f0e1d2a3b"}'
```
