Zum Hauptinhalt springen
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. 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.
Kontakt-ids 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 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. 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.
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.
  • 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.