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.

Effectuer une demande de recherche

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 :

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

Objets CRM

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.

Use this table to describe parameters / fields
Point de terminaison de rechercheObjetPropriétés renvoyées par défaut
/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

Engagements

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.

Use this table to describe parameters / fields
Point de terminaison de rechercheL'engagementPropriétés renvoyées par défaut
/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

Filtrer les résultats de la recherche

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.

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" } ] } ] }'

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 un filterGroup.

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. 

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" } ] } ] }'

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 :

Use this table to describe parameters / fields
OpérateurDescription
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 highValue et value. Consultez l'exemple ci-dessous.

IN

Inclus dans la liste spécifiée. Dans votre demande, ajoutez les valeurs de liste dans un tableau values. Cet opérateur est sensible à la casse. Les valeurs saisies doivent donc être en minuscules. Consultez l'exemple ci-dessous.

NOT_IN

Non inclus dans la liste spécifiée. Dans votre demande, ajoutez les valeurs de liste dans un tableau values. Cet opérateur est sensible à la casse. Les valeurs saisies doivent donc être en minuscules.

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 *@hubspot.com pour récupérer des contacts avec une adresse e-mail HubSpot.

NOT_CONTAINS_TOKEN

Ne contient pas de jeton

À titre d'exemple supplémentaire, vous pouvez utiliser l'opérateur BETWEEN pour rechercher toutes les tâches qui ont été modifiées pour la dernière fois dans une plage horaire spécifique :

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" } ] } ] }'

Autre exemple, vous pouvez utiliser l'opérateur IN pour rechercher toutes les transactions à des phases spécifiques de votre pipeline : 

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"] } ] } ] }'

Rechercher dans des associations

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 :

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" } ] }'

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.

Trier les résultats de la recherche

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 :

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

Recherchez des propriétés par défaut interrogeables

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.

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

Voici les propriétés qui sont recherchées par défaut par la méthode ci-dessus :

Use this table to describe parameters / fields
Point de terminaison de rechercheObjetPropriétés par défaut pouvant être recherchées
/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

Toutes les propriétés d'objet personnalisé peuvent être recherchées par défaut

/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

Il n'y a pas de propriétés par défaut pouvant être recherchées pour les lignes de produit

Préciser les propriétés renvoyées

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 :

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

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.

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

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 :

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

Limites

  • 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.
Cet article vous a-t-il été utile ?
Ce formulaire est destiné à recueillir les avis sur la documentation pour les développeurs. Si vous souhaitez faire part de votre avis sur les produits HubSpot, veuillez le partager sur le forum des idéesde la communauté.