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

```json
{
  "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

```bash
curl -X GET 'https://api.mbcom.cloud/api/crm/v1/interactions' \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```
