> ## Documentation Index
> Fetch the complete documentation index at: https://docs.armin.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# Kontakte und Tickets suchen

> Kund:innen per E-Mail oder Name finden, alle ihre Tickets auflisten und Tickets so durchsuchen wie in der Suchleiste des Posteingangs.

Mit der Suche beantwortet deine Integration die Frage „Wer ist diese Person, und worüber haben wir schon gesprochen?“, ohne alle Tickets durchzublättern. Suche einen Kontakt per E-Mail oder Name, liste alle Tickets dieses Kontakts auf oder finde Tickets über Wörter.

Die Ticket-Suche und die Kontakt-Suche nutzen dieselbe Suche wie die Suchleiste im Posteingang. Sie finden dieselben Tickets und Kontakte wie ein Agent, der dieselben Wörter eintippt.

Alle Such-Endpoints sind rein lesend und liefern nur Daten der Organisation, zu der dein API-Schlüssel gehört.

## Wann du sie nutzt

* **Kund:in erkennen**: Ein Shopsystem oder KI-Agent hat eine E-Mail-Adresse und braucht den passenden Kontakt, inklusive Duplikaten.
* **Verlauf zeigen**: Alle Tickets eines Kontakts auflisten: offen, gelöst und geschlossen.
* **Frühere Gespräche finden**: Nach einer Sendungsnummer, einem Produktnamen oder einer Phrase in Tickets suchen, auch in alten.

## Kontakt suchen

`GET /public/v1/contacts/search` benötigt den Scope **`contacts:read`**. Übergib genau einen der Parameter `email` oder `name`.

| Parameter | Findet |
| - | - |
| `email` | Die E-Mail des Kontakts oder eine zusätzliche E-Mail-Adresse (Groß-/Kleinschreibung egal). Eine andere Adresse derselben Domain passt nicht. Doppelte Kontakte mit derselben Adresse werden alle geliefert. |
| `name` | Mindestens 3 Zeichen, ganze Wörter (`Jane` findet `Jane Doe`, `Jan` nicht). |

Beide nutzen dieselbe Suche wie die Suchleiste im Posteingang. Die besten Treffer kommen zuerst, höchstens 12. Der Suchindex wird asynchron aktualisiert, ein gerade erst erstellter Kontakt wird deshalb eventuell noch nicht gefunden.

```bash theme={null}
curl -sS -H "cx-api-key: $KEY" \
  "https://api.armin.cx/public/v1/contacts/search?email=jane@example.com"
```

Kontakt-`id`s sind stabil. Zusammengeführte Kontakte sind nicht durchsuchbar. Du erhältst den verbleibenden Kontakt, die Tickets wurden übertragen. Ein leeres `data`-Array bedeutet: Kein Kontakt passt.

## Tickets eines Kontakts auflisten

`GET /public/v1/contacts/{contactId}/tickets` benötigt den Scope **`tickets:read`**. Der Endpoint liefert alle Tickets des Kontakts in jedem Status, im selben Format, in derselben Reihenfolge und mit derselben [Cursor-Pagination](https://docs.armin.cx/de/api/pagination.md) wie `GET /tickets`.

Mit `ticket_number` liest du ein Ticket über `GET /tickets/{ticketNumber}` und `GET /tickets/{ticketNumber}/messages`. Eine Kontakt-ID, die es in deiner Organisation nicht gibt, ergibt `404 CONTACT_NOT_FOUND`.

## Tickets suchen

`GET /public/v1/tickets/search` benötigt den Scope **`tickets:read`**.

| Parameter | Beschreibung |
| - | - |
| `q` | Gesuchte Wörter, 2 bis 100 Zeichen |
| `sort` | `relevance` (Standard, beste Treffer zuerst), `newest` oder `oldest`. Neueste und älteste nutzen das Erstellungsdatum des Tickets. |
| `limit` | Ergebnisse pro Seite, 1 bis 50 (Standard 20) |
| `cursor` | `pagination.next_cursor` der vorherigen Seite |

Ein Ticket passt über Betreff, KI-Zusammenfassung, Ticketnummer, Dateinamen von Anhängen, Nachrichten oder Name und E-Mail des Kontakts. Die Suche arbeitet mit ganzen Wörtern: `Erstattung` findet nicht `Erstattungen`.

```bash theme={null}
curl -sS -G -H "cx-api-key: $KEY" \
  "https://api.armin.cx/public/v1/tickets/search" \
  --data-urlencode "q=kaputt angekommen"
```

Jedes Ergebnis ist ein Ticket im selben Format wie bei `GET /tickets`. Die Ergebnisse enthalten jeden Status. Standardmäßig kommen sie **nach Relevanz sortiert**. Mit `sort=newest` oder `sort=oldest` sortierst du stattdessen nach Erstellungsdatum.

Die Operatoren der Posteingangs-Suche funktionieren in `q`: `from:`, `to:`, `channel:`, `has:attachment` und `newer_than:`. `from:me` und `to:me` werden ignoriert, weil ein API-Schlüssel keinen angemeldeten Agenten hat.

## Pagination

Übergib `pagination.next_cursor` unverändert, um die nächste Seite zu laden. Eine Seite kann weniger als `limit` Tickets enthalten, zum Beispiel wenn ein Ticket gerade gelöscht wurde. Mach weiter, solange `pagination.has_more` `true` ist.

Die Suche erreicht etwa die besten 500 Treffer. Für mehr Tiefe machst du die Suche genauer.

Der Suchindex wird asynchron aktualisiert. Ein Ticket oder eine Nachricht, die gerade erst erstellt oder bearbeitet wurde, wird deshalb eventuell noch nicht gefunden.

## Best Practices

* Nutze `email` statt `name`, wenn du sie hast. Sie ist präziser und liefert Duplikate, die du eventuell abgleichen musst.
* Weiche bei `429` aus. Die Suche hat ein eigenes Limit von 30 Requests pro Minute. Siehe [Rate Limits](https://docs.armin.cx/de/api/rate-limits.md).
* Vergib `contacts:read` nur an Schlüssel, die Kund:innen nachschlagen müssen. Schlüssel mit expliziten Scopes erhalten ihn nicht automatisch, erstelle also einen neuen Schlüssel mit dem Scope. Legacy-Schlüssel ohne Scopes behalten vollen Zugriff.

## Grenzen

* Die Suche liefert nur Tickets und Kontakte. Sie liefert keine Textausschnitte und erklärt nicht, warum ein Ticket passt.
* Telefonnummern, eigene Ticketfelder und Filter wie Status oder Tag sind nicht durchsuchbar. Zum Filtern von Tickets nutzt du eine [gespeicherte Ansicht](https://docs.armin.cx/de/api/filtering-and-saved-views.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.