## Assign an interaction to a customer (tenant:crm:write)

`PUT /api/crm/v1/interactions/{id}/address`

Module: CRM · operationId: `assignInteraction` · Tag: Interactions · Auth: access token (`Authorization: Bearer <accessToken>`)

Sets the masterdata address (checked in masterdata, `422` `invalid_reference` when unknown) and optionally the
contact of an interaction in crm. The assignment stays in crm – later updates of comms keep it, and comms
learns nothing from it. An interaction tracked as an activity keeps its customer (`409` `already_tracked`).

### Parameters

| Name | In | Type | Required | Description |
|---|---|---|---|---|
| `id` | path | string (uuid) | yes | The interaction id (comms). |

### Request body

`application/json` (required)

- `addressId` (string (uuid), required): The customer (masterdata address of the tenant).
- `contactId` (string (uuid)): Contact person of that address.

Example:

```json
{
  "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "contactId": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a"
}
```

### Responses

- **200** The assigned interaction (`application/json`)
- **400** Invalid input (`invalid`): `field` names the first invalid field, `details.fields` every one (JSON paths for
bodies, parameter names for the query). Some refusals have their own code (`invalid_sort`,
`invalid_stages`, `invalid_custom_fields`, `convert_target_required`, `invalid_csv`, …).
 (`application/json`)
- **401** Missing, invalid or expired token (no body).
- **403** The token lacks the permission (`insufficient permissions`) or has no active tenant.
 (`application/json`)
- **404** The record does not exist in the token's tenant. (`application/json`)
- **409** The state of the record (or the tenant's settings) does not allow the request; `code` says why. (`application/json`)
- **422** A referenced record (lead, masterdata address) does not exist in the tenant. (`application/json`)
- **500** Unexpected error; details are only logged. (`application/json`)
- **502** An upstream service (masterdata, VAT check) failed, is switched off or is not configured. (`application/json`)

Fields of the 200 answer:

- `durationSeconds` (integer, required): Duration in seconds.
- `id` (string (uuid), required): The interaction id of comms.
- `kind` (string, required): call, meeting or remote_session.
- `provider` (string, required): Integration that recorded it (nfon, teams, teamviewer).
- `startedAt` (string (date-time), required): Start of the interaction.
- `updatedAt` (string (date-time), required): Time of the last change.
- `activityId` (string (uuid)): The crm activity the interaction is tracked as.
- `addressId` (string (uuid)): The customer (masterdata address); missing while unassigned.
- `contactId` (string (uuid)): Contact person of the address; missing when not known.
- `counterpartName` (string): Name of the other side.
- `direction` (string): Direction of a call, e.g. inbound or outbound.
- `endedAt` (string (date-time)): End of the interaction; omitted while unknown.
- `outcome` (string): Outcome reported by the provider, e.g. answered.
- `personName` (string): Name of that person.
- `personRef` (string): E-mail of the person of the tenant who had the interaction (lower case).
- `phone` (string): Phone number of the other side (calls).

Example 200 answer:

```json
{
  "addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
  "contactId": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a",
  "counterpartName": "Katrin Stadler",
  "direction": "inbound",
  "durationSeconds": 487,
  "endedAt": "2026-11-16T09:20:07Z",
  "id": "4f6a8c0e-2b4d-4f6a-8c0e-2b4d6f8a0c2e",
  "kind": "call",
  "outcome": "answered",
  "personName": "Sophie Huber",
  "personRef": "sophie.huber@muster-it.example",
  "phone": "+498652987612",
  "provider": "nfon",
  "startedAt": "2026-11-16T09:12:00Z",
  "updatedAt": "2026-11-16T09:20:09Z"
}
```

### Example request

```bash
curl -X PUT 'https://api.mbcom.cloud/api/crm/v1/interactions/3f2b8c1e-7d4a-4e9b-9c2a-5b1d6e8f0a12/address' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"addressId":"3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e","contactId":"8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a"}'
```
