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.

Eine Suchanfrage durchführen

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:

// Example POST request to /crm/v3/objects/contacts/search {}

CRM-Objekte

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.

Use this table to describe parameters / fields
Suche-EndpunktObjektStandardmäßig zurückgegebene Eigenschaften
/crm/v3/objects/companies/search
Companies

name, domain, createdate,

hs_lastmodifieddate, hs_object_id

/crm/v3/objects/contacts/search
Contacts

firstname,lastname,email,lastmodifieddate,hs_object_id, createdate

/crm/v3/objects/{objectType}/search
Custom objects

hs_createdate,hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/deals/search
Deals

dealname, amount, closedate,
pipeline,dealstage, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/feedback_submissions/search
Feedback submissions

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/line_items/search
Line items

quantity, amount, price, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/products/search
Products

name, description ,price, createdate, hs_lastmodifieddate, hs_object_id

/crm/v3/objects/quotes/search
Quotes

hs_expiration_date, hs_public_url_key, hs_status,

hs_title, hs_createdate, hs_lastmodifieddate,

hs_object_id

/crm/v3/objects/tickets/search
Tickets

content, hs_pipeline, hs_pipeline_stage,

hs_ticket_category, hs_ticket_priority, subject,

createdate, hs_lastmodifieddate, hs_object_id

Interaktionen

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.

Use this table to describe parameters / fields
Suche-EndpunktInteraktionenStandardmäßig zurückgegebene Eigenschaften
/crm/v3/objects/calls/search
Calls

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/emails/search
Emails

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/meetings/search
Meetings

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/notes/search
Notes

hs_createdate,
hs_lastmodifieddate,
hs_object_id

/crm/v3/objects/tasks/search
Tasks

hs_createdate,
hs_lastmodifieddate,
hs_object_id

Suchergebnisse filtern

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.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[ { "filters":[ { "propertyName": "firstname", "operator": "EQ", "value": "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 einer filterGroup 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. 

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups": [ { "filters": [ { "propertyName": "firstname", "operator": "EQ", "value": "Alice" }, { "propertyName": "lastname", "operator": "NEQ", "value": "Smith" } ] }, { "filters": [ { "propertyName": "email", "operator": "NOT_HAS_PROPERTY" } ] } ] }'

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:

Use this table to describe parameters / fields
OperatorDescription
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 highValue und value festzulegen. Beachten Sie das Beispiel unten.

IN

In der angegebenen Liste enthalten. Fügen Sie in Ihrer Anfrage die Listenwerte in ein values-Array ein. Bei diesem Operator wird zwischen Groß- und Kleinschreibung unterschieden. Die eingegebenen Werte müssen daher in Kleinbuchstaben geschrieben werden. Beachten Sie das Beispiel unten.

NOT_IN

Not included within the specified list. Fügen Sie in Ihrer Anfrage die Listenwerte in ein values-Array ein. Bei diesem Operator wird zwischen Groß- und Kleinschreibung unterschieden. Die eingegebenen Werte müssen daher in Kleinbuchstaben geschrieben werden.

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 *@hubspot.com, um Kontakte mit einer HubSpot-E-Mail-Adresse abzurufen.

NOT_CONTAINS_TOKEN

Enthält kein Token

Sie können zum Beispiel den BETWEEN-Operator verwenden, um nach allen Aufgaben zu suchen, die zuletzt innerhalb eines bestimmten Zeitraums geändert wurden:

curl https://api.hubapi.com/crm/v3/objects/tasks/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"hs_lastmodifieddate", "operator":"BETWEEN", "highValue": "1642672800000", "value":"1579514400000" } ] } ] }'

Als weiteres Beispiel können Sie den IN-Operator verwenden, um nach allen Deals in bestimmten Phasen Ihrer Pipeline zu suchen: 

curl https://api.hubapi.com/crm/v3/objects/deals/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filterGroups":[{ "filters":[ { "propertyName":"dealstage", "operator":"IN", "values": ["appointmentscheduled", "contractsent", "qualifiedtobuy"] } ] } ] }'

Zuordnungen durchsuchen

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:

curl https://api.hubapi.com/crm/v3/objects/tickets/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "filters": [ { "propertyName": "associations.contact", "operator": "EQ", "value": "123" } ] }'

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.

Suchergebnisse sortieren

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:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "sorts": [ { "propertyName": "createdate", "direction": "DESCENDING" } ] }'

Standardmäßig durchsuchbare Eigenschaften durchsuchen

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.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "query": "x" }'

Nachfolgend finden Sie die Eigenschaften, die standardmäßig mit der oben genannten Methode gesucht werden:

Use this table to describe parameters / fields
Suche-EndpunktObjektStandardmäßig durchsuchbare Eigenschaften
/crm/v3/objects/calls/search
Calls

hs_call_title, hs_body_preview

/crm/v3/objects/companies/search
Companies

website, phone, name, domain

/crm/v3/objects/contacts/search
Contacts

firstname,lastname,email,phone,hs_additional_emails, fax, mobilephone, company, hs_marketable_until_renewal

/crm/v3/objects/{objectType}/search
Custom objects

Alle benutzerdefinierten Objekteigenschaften sind standardmäßig durchsuchbar

/crm/v3/objects/deals/search
Deals

dealname,pipeline,dealstage, description, dealtype

/crm/v3/objects/emails/search
Emails

hs_email_subject

/crm/v3/objects/feedback_submissions/search
Feedback submissions

hs_submission_name, hs_content

/crm/v3/objects/meetings/search
Meetings

hs_meeting_title, hs_meeting_body

/crm/v3/objects/notes/search
Notes

hs_note_body

/crm/v3/objects/products/search
Products

name, description ,price, hs_sku

/crm/v3/objects/quotes/search
Quotes

hs_sender_firstname, hs_sender_lastname, hs_proposal_slug, hs_title, hs_sender_company_name, hs_sender_email, hs_quote_number, hs_public_url_key

/crm/v3/objects/tasks/search
Tasks

hs_task_body, hs_task_subject

/crm/v3/objects/tickets/search
Tickets

subject, content, hs_pipeline_stage, hs_ticket_category, hs_ticket_id

/crm/v3/objects/line_items/search
Line items

Es gibt keine standardmäßig durchsuchbaren Eigenschaften für Artikel

Zurückgegebene Eigenschaften angeben

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:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "properties": [ "email", "state" ] }'

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.

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "limit": 20 }

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:

curl https://api.hubapi.com/crm/v3/objects/contacts/search \ --request POST \ --header "Content-Type: application/json" \ --data '{ "after": "20" }'

Beschränkungen

  • 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.
War dieser Artikel hilfreich?
Dieses Formular dient dazu, Feedback zu unserer Entwicklerdokumentation zu sammeln. Wenn Sie uns Ihre Meinung zu HubSpot-Produkten mitteilen möchten, teilen Sie diese bitte im Ideenforum der Community.