ConnectCloud Developers

List interactions of a customer or without a customer (tenant:crm:read)

GET /api/crm/v1/interactions

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

Calls, meetings and remote sessions comms recorded from the tenant's integrations (NFON, Microsoft Teams, TeamViewer) and crm follows on comms' feed – metadata only (kind, who, with whom, when, how long, direction, outcome); interactions between people of the tenant are not kept. Pass exactly one of addressId (the customer's timeline: the address comms suggested or someone assigned) and unassigned=true (interactions without a customer, e.g. unknown numbers); otherwise 400 (interaction_filter_required). Newest first, keyset paging. Transcript and summary are never listed: they appear on the activity the person who had the interaction tracks it as (POST /api/crm/v1/interactions/{id}/activity).

Parameters

Name In Type Required Description
addressId query string (uuid)
unassigned query boolean true: only interactions without a customer.
limit query integer Page size, 1–200 (default 50); any other value is 400 invalid. (default 50; max 200)
cursor query string nextCursor of the previous page; leave out for the first page. Keep sort and the filters unchanged while paging: a cursor of another sort or an altered one is 400 invalid (field: cursor). (max length 1024)

Responses

  • 200 A page of interactions (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)
  • 500 Unexpected error; details are only logged. (application/json)

Fields of the 200 answer:

  • items (array of Interaction, required): One page of interactions.
    • 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).
  • nextCursor (string): Cursor of the next page (pass it as cursor); missing on the last page.

Example 200 answer:

{
  "items": [
    {
      "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 GET 'https://api.mbcom.cloud/api/crm/v1/interactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"

View as Markdown · Interactive reference · OpenAPI