Suche
Mit den CRM-Suche-Endpunkten können Sie Objekte, Datensätze und Interaktionen überall in Ihrem CRM-System filtern, sortieren und suchen. Verwenden Sie beispielsweise die Endpunkte, um eine Liste mit Kontakten in Ihrem Account oder eine Liste aller offenen Deals abzurufen.
Um diese Endpunkte über eine App zu verwenden, ist ein CRM-Bereich erforderlich. In dieser Liste der verfügbaren Bereiche erfahren Sie, welche granularen CRM-Bereiche verwendet werden können, um Ihr Ziel zu erreichen.
Um Ihr CRM-System zu durchsuchen, führen Sie eine POST
-Anfrage an den Suche-Endpunkt des Objekts durch. CRM-Suche-Endpunkte weisen das folgende Format auf:
/crm/v3/objects/{object}/search
Um eine einfache Suche durchzuführen, bei der nur Standardeigenschaften ohne zusätzliche Filterung oder Sortierung zurückgegeben werden, schließen nur ein leeres Objekt in den Anfragetext ein. Zum Beispiel:
Die folgenden Tabellen enthalten die Suche-Endpunkte für Objekte, die Objekte, auf die sie sich beziehen, und die Eigenschaften, die standardmäßig zurückgegeben werden. Erfahren Sie mehr über das Angeben von zurückgegebenen Eigenschaften.
Suche-Endpunkt | Objekt | Standardmäßig zurückgegebene Eigenschaften |
---|---|---|
/crm/v3/objects/companies/search
| Companies |
|
/crm/v3/objects/contacts/search
| Contacts |
|
/crm/v3/objects/{objectType}/search
| Custom objects |
|
/crm/v3/objects/deals/search
| Deals |
|
/crm/v3/objects/feedback_submissions/search
| Feedback submissions |
|
/crm/v3/objects/line_items/search
| Line items |
|
/crm/v3/objects/products/search
| Products |
|
/crm/v3/objects/quotes/search
| Quotes |
|
/crm/v3/objects/tickets/search
| Tickets |
|
Die folgende Tabelle enthält die Suche-Endpunkte für Interaktionen, die Interaktionen auf die sie sich beziehen, und die Eigenschaften, die standardmäßig zurückgegeben werden. Erfahren Sie mehr über das Angeben von zurückgegebenen Eigenschaften.
Suche-Endpunkt | Interaktionen | Standardmäßig zurückgegebene Eigenschaften |
---|---|---|
/crm/v3/objects/calls/search
| Calls |
|
/crm/v3/objects/emails/search
| Emails |
|
/crm/v3/objects/meetings/search
| Meetings |
|
/crm/v3/objects/notes/search
| Notes |
|
/crm/v3/objects/tasks/search
| Tasks |
|
Verwenden Sie Filter („filters“) im Anfragetext, um die Ergebnisse nur auf Datensätze mit übereinstimmenden Eigenschaftswerten zu begrenzen. Beispielsweise sucht die untenstehende Anfrage nach allen Kontakten mit dem Vornamen von Alice.
Um mehrere Filterkriterien einzubeziehen, können Sie filters
innerhalb von filterGroups
gruppieren:
- Um AND-Verknüpfung anzuwenden, fügen Sie eine durch Kommata getrennte Liste von Bedingungen innerhalb eines Satzes von
filters
hinzu. - Um OR-Logik anzuwenden, fügen Sie mehrere
filters
mit einerfilterGroup
hinzu.
Sie können maximal drei filterGroups
mit bis zu drei filters
in jede Gruppe aufnehmen.
Beispielsweise sucht die unten stehende Anfrage nach Kontakten mit dem Vornamen Alice
UND einem anderen Nachnamen als Smith
oder nach Kontakten, die keinen Wert für die Eigenschaft email
aufweisen.
Sie können Operatoren in Filtern verwenden, um anzugeben, welche Datensätze zurückgegeben werden sollen. Bei den Werten in den Filtern wird nicht zwischen Groß- und Kleinschreibung unterschieden, mit Ausnahme der Operatoren IN
und NOT_IN
. Sie können die folgenden Operatoren in einem Filter verwenden:
Operator | Description |
---|---|
LT
| Kleiner als |
LTE
| Kleiner als oder gleich |
GT
| Größer als |
GTE
| Größer als oder gleich |
EQ
| Gleich |
NEQ
| Ungleich |
BETWEEN
| Innerhalb des angegebenen Bereichs. Verwenden Sie in Ihrer Anfrage Schlüssel-Wert-Paare, um |
IN
| In der angegebenen Liste enthalten. Fügen Sie in Ihrer Anfrage die Listenwerte in ein |
NOT_IN
| Not included within the specified list. Fügen Sie in Ihrer Anfrage die Listenwerte in ein |
HAS_PROPERTY
| Hat einen Wert für die angegebene Eigenschaft |
NOT_HAS_PROPERTY
| Hat keinen Wert für die angegebene Eigenschaft |
CONTAINS_TOKEN
| Enthält ein Token. In Ihrer Anfrage können Sie Platzhalter (*) verwenden, um eine teilweise Suche durchzuführen. Verwenden Sie beispielsweise den Wert |
NOT_CONTAINS_TOKEN
| Enthält kein Token |
Suchen Sie nach Datensätzen, die mit anderen spezifischen Datensätzen verknüpft sind, indem Sie die Pseudo-Eigenschaft associations.{objectType}
verwenden.
Beispielsweise sucht die folgende Anfrage nach allen Tickets, die einem Kontakt zugeordnet sind, der die Kontakt-ID 123
hat:
Sie können Zuordnungen mithilfe der folgenden Pseudo-Eigenschaftswerte durchsuchen:
associations.company
associations.contact
associations.ticket
associations.deal
associationS.quote
Bitte beachten: Die Option zum Durchsuchen benutzerdefinierter Objektzuordnungen wird derzeit nicht über Suche-Endpunkte unterstützt. Um benutzerdefinierte Objektzuordnungen zu finden, können Sie die Zuordnungs-API verwenden.
Verwenden Sie eine Sortierungsregel im Anfragetext, um Ergebnisse in aufsteigender oder absteigender Reihenfolge aufzulisten. Bei jeder Suche kann nur jeweils eine Sortierungsregel angewendet werden.
Beispielsweise sortiert die untenstehende Anfrage zurückgegebene Kontakte mit den zuletzt erstellten zuerst:
Durchsuchen Sie alle Standardtexteigenschaften in Datensätzen des angegebenen Objekts, um alle Datensätze zu finden, die einen Wert haben, der die angegebene Zeichenfolge enthält. Standardmäßig werden die Ergebnisse in der Reihenfolge der Objekterstellung zurückgegeben (älteste erste), aber Sie können diese mithilfe von Sortierung überschreiben.
Beispielsweise wird mit der Anfrage unten nach allen Kontakten mit einem Standardtext-Eigenschaftswert gesucht, der den Buchstaben X
enthält.
Nachfolgend finden Sie die Eigenschaften, die standardmäßig mit der oben genannten Methode gesucht werden:
Suche-Endpunkt | Objekt | Standardmäßig durchsuchbare Eigenschaften |
---|---|---|
/crm/v3/objects/calls/search
| Calls |
|
/crm/v3/objects/companies/search
| Companies |
|
/crm/v3/objects/contacts/search
| Contacts |
|
/crm/v3/objects/{objectType}/search
| Custom objects | Alle benutzerdefinierten Objekteigenschaften sind standardmäßig durchsuchbar |
/crm/v3/objects/deals/search
| Deals |
|
/crm/v3/objects/emails/search
| Emails |
|
/crm/v3/objects/feedback_submissions/search
| Feedback submissions |
|
/crm/v3/objects/meetings/search
| Meetings |
|
/crm/v3/objects/notes/search
| Notes |
|
/crm/v3/objects/products/search
| Products |
|
/crm/v3/objects/quotes/search
| Quotes |
|
/crm/v3/objects/tasks/search
| Tasks |
|
/crm/v3/objects/tickets/search
| Tickets |
|
/crm/v3/objects/line_items/search
| Line items | Es gibt keine standardmäßig durchsuchbaren Eigenschaften für Artikel |
Jede Anfrage gibt einen Standardsatz von Eigenschaften in ihren Suchergebnissen für das angeforderte Objekt zurück. Sie können dies überschreiben, indem Sie ein Array von spezifischen Eigenschaftsnamen im properties
-Parameter Ihres Anfragetextes angeben.
Beispielsweise durchsucht die untenstehende Anfrage alle Kontakte und gibt deren E-Mail und Status zurück:
Durchblättern von Ergebnissen
Standardmäßig geben Suche-Endpunkte Seiten mit jeweils 10 Datensätzen zurück. Dies kann mithilfe des limit
-Parameters im Anfragetext geändert werden. Die maximale Anzahl unterstützter Objekte pro Seite beträgt 100.
Die folgende Anfrage gibt beispielsweise Seiten mit jeweils 20 Ergebnissen zurück.
Um die nächste Seite der Ergebnisse aufzurufen, müssen Sie einen in der paging.next.after
-Eigenschaft der vorherigen Antwort angegebenen after
-Parameter übergeben. Wenn die paging.next.after
-Eigenschaft nicht angegeben wurde, gibt es keine zusätzlichen Ergebnisse zum Anzeigen. Sie müssen den Wert im after
-Parameter als Integer formatieren.
Beispielsweise gibt die folgende Anfrage die nächste Seite der Ergebnisse zurück:
- Es kann einige Momente dauern, bis neu erstellte oder aktualisierte CRM-Objekte in Suchergebnissen angezeigt werden.
- Archivierte CRM-Objekte werden nicht in Suchergebnissen angezeigt.
- Bei Suche-Endpunkten gibt es eine Ratenbegrenzung von vier Anfragen pro Sekunde.
- Eine Abfrage kann maximal 3.000 Zeichen enthalten. Wenn der Hauptteil Ihrer Anfrage 3.000 Zeichen überschreitet, wird ein 400-Fehler zurückgegeben.
- Die Suche-Endpunkte sind für jede Abfrage auf 10.000 Gesamtergebnisse beschränkt. Wenn Sie versuchen, über 10.000 Seiten zu blättern, tritt ein 400-Fehler auf.
- Bei der Suche nach Telefonnummern verwendet HubSpot spezielle berechnete Eigenschaften, um das Format zu standardisieren. Diese Eigenschaften beginnen alle mit
hs_searchable_calculated_*
. Im Rahmen dieser Standardisierung verwendet HubSpot nur die Ortsvorwahl und die lokale Nummer. Sie sollten darauf verzichten, den Ländercode in Ihren Such- oder Filterkriterien zu berücksichtigen.
Vielen Dank, dass Sie Ihr Feedback mit uns geteilt haben.