Recherche
Utilisez les points de terminaison de recherche dans le CRM pour filtrer, trier et rechercher des objets, des fiches d'informations et des interactions dans votre CRM. Par exemple, utilisez les points de terminaison pour obtenir une liste de contacts dans votre compte ou une liste de toutes les transactions ouvertes.
Un périmètre d'accès CRM est obligatoire pour utiliser ces points de terminaison depuis une application. Reportez-vous à cette liste de périmètres d'accès disponibles pour savoir quels périmètres d'accès CRM granulaires peuvent être utilisés pour atteindre votre objectif.
Pour rechercher dans votre CRM, effectuez une demande POST
au point de terminaison de recherche de l'objet. Les points de terminaison de recherche dans le CRM sont créés selon le format suivant :
/crm/v3/objects/{object}/search
Pour effectuer une recherche de base, renvoyer uniquement les propriétés par défaut sans filtrage ni tri supplémentaire, incluez uniquement un objet vide dans le corps de la demande. Par exemple :
Les tableaux ci-dessous contiennent les points de terminaison de recherche d'objets, les objets auxquels ils se réfèrent et les propriétés renvoyées par défaut. Découvrez-en davantage sur la spécification des propriétés renvoyées.
Point de terminaison de recherche | Objet | Propriétés renvoyées par défaut |
---|---|---|
/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 |
|
Le tableau ci-dessous contient les points de terminaison de recherche d'engagement, les engagements auxquels ils se réfèrent et les propriétés renvoyées par défaut. Découvrez-en davantage sur la spécification des propriétés renvoyées.
Point de terminaison de recherche | L'engagement | Propriétés renvoyées par défaut |
---|---|---|
/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 |
|
Utilisez les filtres dans le corps de la demande pour limiter les résultats uniquement aux objets de CRM avec les valeurs de propriété correspondantes. Par exemple, la demande ci-dessous recherche tous les contacts avec le prénom Alice.
Pour inclure plusieurs critères de filtre, vous pouvez regrouper les filters
dans filterGroups
:
- Pour appliquer une logique ET, incluez une liste de conditions séparées par des virgules dans un ensemble de
filters
. - Pour appliquer la logique OU, incluez plusieurs
filters
avec unfilterGroup
.
Vous pouvez inclure au maximum trois filterGroup
contenant chacun jusqu'à trois filters
.
Par exemple, la demande ci-dessous recherche des contacts avec le prénom Alice
ET un nom de famille autre que Smith
, ou des contacts qui n'ont pas de valeur pour la propriété email
.
Vous pouvez utiliser des opérateurs dans les filtres pour spécifier les fiches d'informations à renvoyer. Les valeurs dans les filtres sont insensibles à la casse, à l'exception des opérateurs IN
et NOT_IN
. Vous pouvez utiliser les opérateurs suivants dans un filtre :
Opérateur | Description |
---|---|
LT
| Est inférieur à |
LTE
| Est inférieur ou égal à |
GT
| Est supérieur à |
GTE
| Est supérieur ou égal à |
EQ
| Est égal à |
NEQ
| N'est pas égal à |
BETWEEN
| Dans la plage spécifiée. Dans votre demande, utilisez des paires (clé, valeur) pour définir |
IN
| Inclus dans la liste spécifiée. Dans votre demande, ajoutez les valeurs de liste dans un tableau |
NOT_IN
| Non inclus dans la liste spécifiée. Dans votre demande, ajoutez les valeurs de liste dans un tableau |
HAS_PROPERTY
| A une valeur pour la propriété spécifiée |
NOT_HAS_PROPERTY
| N'a pas de valeur pour la propriété spécifiée |
CONTAINS_TOKEN
| Contient un jeton. Dans votre demande, vous pouvez utiliser des caractères génériques (*) pour effectuer une recherche partielle. Par exemple, utilisez la valeur |
NOT_CONTAINS_TOKEN
| Ne contient pas de jeton |
Recherchez des fiches d'informations associées à d'autres fiches d'informations spécifiques en utilisant la pseudo-propriété associations.{objectType}
.
Par exemple, la demande ci-dessous recherche tous les tickets associés à un contact dont l'ID de contact est 123
:
Vous pouvez rechercher dans des associations en utilisant les valeurs de pseudo-propriété suivantes :
associations.company
associations.contact
associations.ticket
associations.deal
associations.quote
Remarque : L'option de recherche dans des associations d'objets personnalisés n'est actuellement pas prise en charge via des points de terminaison de recherche. Pour trouver des associations d'objets personnalisés, vous pouvez utiliser l'API d'associations.
Utilisez une règle de tri dans le corps de la demande pour lister les résultats dans l'ordre croissant ou décroissant. Une seule règle de tri peut être appliquée à une recherche.
Par exemple, la demande ci-dessous trie les contacts renvoyés selon la plus récente création :
Recherchez toutes les propriétés de texte par défaut dans des fiches d'informations de l'objet spécifié pour trouver toutes les fiches d'informations ayant une valeur contenant la chaîne spécifiée. Par défaut, les résultats seront renvoyés selon la date de création des objets (les plus anciens en premier), mais vous pouvez remplacer cela grâce au tri.
Par exemple, la demande ci-dessous recherche tous les contacts avec une valeur de propriété de texte par défaut contenant la lettre X
.
Voici les propriétés qui sont recherchées par défaut par la méthode ci-dessus :
Point de terminaison de recherche | Objet | Propriétés par défaut pouvant être recherchées |
---|---|---|
/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 | Toutes les propriétés d'objet personnalisé peuvent être recherchées par défaut |
/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 | Il n'y a pas de propriétés par défaut pouvant être recherchées pour les lignes de produit |
Chaque demande renvoie un ensemble de propriétés par défaut dans ses résultats de recherche pour l'objet demandé. Vous pouvez remplacer cela en fournissant des noms de propriétés spécifiques dans le paramètre properties
de le corps de votre requête.
Par exemple, la demande ci-dessous recherche tous les contacts et renverra leur e-mail et indiquera :
Pagination des résultats
Par défaut, les points de terminaison de recherche renvoient des pages de 10 fiches d'informations. Cela peut être modifié en définissant le paramètre limit
dans le corps de votre demande. Le nombre maximum d'objets pris en charge par page est de 100.
Par exemple, la demande ci-dessous renverra des pages contenant 20 résultats chacune.
Pour accéder à la page de résultats suivante, vous devez inclure le paramètre after
fourni dans la propriété paging.next.after
de la réponse précédente. Si la propriété paging.next.after
n'est pas fournie, il n'y aura aucun résultat supplémentaire à afficher. Vous devez formater la valeur dans le paramètre after
sous forme de nombre entier.
Par exemple, la demande ci-dessous renverra la page de résultats suivante :
- L'affichage d'objets CRM nouveaux ou mis à jour dans les résultats de recherche peut prendre quelques instants.
- Les objets de CRM archivés ne s'afficheront pas dans les résultats de recherche.
- Les points de terminaison de recherche sont limités à quatre demandes par seconde.
- Une demande peut contenir jusqu'à 3 000 caractères. Si le corps de votre demande dépasse 3 000 caractères, une erreur 400 sera renvoyée.
- Les points de terminaison de recherche sont limités à 10 000 résultats par requête. La tentative de pagination au-delà de 10 000 résultats entraînera une erreur 400.
- Lors de la recherche de numéros de téléphone, HubSpot utilise des propriétés calculées spéciales pour uniformiser le format. Ces propriétés commencent toutes par
hs_searchable_calculated_*
. Dans le cadre de cette uniformisation, HubSpot utilise uniquement l'indicatif régional et le numéro local. Vous ne devez pas inclure le code pays dans vos critères de recherche ou de filtrage.
Merci d'avoir partagé votre avis.