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:
{
"addressId": "3c5e7a9c-1d3f-4b5a-9c7e-1a3c5e7a9c1e",
"contactId": "8b0d2f4b-6c8e-4a0c-9e2a-4c6e8a0c2e4a"
}
Responses
- 200 The assigned interaction (
application/json) - 400 Invalid input (
invalid):fieldnames the first invalid field,details.fieldsevery 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;
codesays 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:
{
"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
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"}'