ConnectCloud Developers

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): 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:

{
  "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"}'

View as Markdown · Interactive reference · OpenAPI