Les points de terminaison pour les associations de CRM sont utilisés pour gérer les associations entre des tickets, des produits, des lignes de produit et leurs contacts, entreprises et transactions associés.
Les associations représentent les relations entre les objets et les activités dans le CRM de HubSpot. Des associations de fiches d’informations peuvent exister entre des fiches d’informations de différents objets (par exemple : de Contact à Entreprise) ou au sein d’un même objet (par exemple : Entreprise à Entreprise). Vous pouvez utiliser les points de terminaison d’associations pour créer, récupérer, mettre à jour, ou supprimer des associations entre des fiches d’informations, ou des fiches d’informations et des activités.Les points de terminaison de schéma d’association vous permettent d’afficher les types d’association pris en charge dans votre compte, ainsi que de créer vos propres types d’association et d’attribuer des libellés à vos relations de fiche d’informations. Les libellés d’association sont pris en charge entre les contacts, les entreprises, les transactions, les tickets et les objets personnalisés, et peuvent être utilisés dans tous les outils HubSpot tels que les listes et les workflows.Découvrez-en davantage sur les API d’objets, de fiches d’informations, de propriétés et d’associations dans le guide Comprendre le CRM.
HubSpot fournit un ensemble de types d’association prédéfinis (par exemple : contact sans libellé de l’entreprise), mais les administrateurs de compte peuvent définir leurs propres libellés d’association pour fournir un contexte supplémentaire pour les relations entre les fiches d’informations (par exemple : responsable et employé). Il existe deux types d’association définis par HubSpot :
Principale : l’entreprise principale à laquelle l’autre fiche d’informations est associée. Les associations principales peuvent être utilisées dans les outils HubSpot tels que les listes et les workflows. Pour les fiches d’informations contenant plusieurs entreprises associées, cette API prend en charge la modification de l’entreprise considérée comme principale.
Sans libellé : un type d’association ajouté lorsqu’une fiche d’informations de contact, d’entreprise, de transaction, de ticket ou d’objet personnalisé est associée. Ce type indique qu’une association existe et sera toujours renvoyée dans les réponses avec une valeur de libellé de null. Lorsqu’une fiche d’informations dispose d’une association principale ou d’un libellé d’association personnalisé, ces types seront répertoriés avec le type d’association sans libellé.
Vous pouvez visualiser tous les types d’association définis par HubSpot dans cette section.
Il existe deux types de libellés d’association que vous pouvez utiliser pour décrire les relations entre des fiches d’informations :
Unique : un libellé qui s’applique aux deux fiches d’informations de la relation. Par exemple : Ami ou Collègue.
Jumelé : une paire de libellés pour les cas où des mots différents sont utilisés pour décrire chaque aspect de la relation des fiches d’informations associées. Par exemple : Parent et Enfant ou Employeur et Employé. Pour créer des libellés appariés, vous devez inclure le champ inverseLabel dans votre demande pour nommer le deuxième libellé de la paire.
Vous pouvez créer des types d’association personnalisés dans HubSpot ou via le point de terminaison d’API du schéma d’association. Vous pouvez créer jusqu’à 10 types d’association entre chaque paire d’objets (par exemple : contacts et entreprises, contacts et contacts).Pour créer un type d’association via l’API, effectuez une demande POST à /crm/v4/associations/{fromObjectType}/{toObjectType}/labels et incluez les éléments suivants dans votre demande :
nom : le nom interne du type d’association. Cette valeur ne peut pas comprendre de traits d’union ni commencer par un caractère numérique.
Pour afficher les types d’association entre des objets spécifiques, effectuez une demande GET à /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.Vous recevrez un tableau contenant chaque élément :
catégorie : si le type d’association a été créé par HubSpot (HUBSPOT_DEFINED) ou par un utilisateur (USER_DEFINED).
Vous pouvez créer une association sans libellé par défaut entre deux fiches d’informations ou configurer des associations sans libellé pour des fiches d’informations en masse. Pour configurer une association individuelle par défaut entre deux fiches d’informations, effectuez une demande PUT à/crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}Dans l’URL de la demande, comprend :
fromObjectType** :** l’ID de l’objet que vous associez. Pour trouver les valeurs d’ID, consultez cette liste d’ID de types d’objet, ou pour les contacts, les entreprises, les transactions, les tickets et les notes, vous pouvez utiliser le nom d’objet (par exemple : contact, company).
fromObjectId** :** l’ID de la fiche d’informations à associer.
toObjectType** :** l’ID de l’objet auquel vous associez la fiche d’informations. Pour trouver les valeurs d’ID, consultez cette liste d’ID de types d’objet, ou pour les contacts, les entreprises, les transactions, les tickets et les notes, vous pouvez utiliser le nom d’objet (par exemple : contact, company).
toObjectId** :** l’ID de la fiche d’informations à associer.
Par exemple : pour associer une fiche d’informations de contact dont l’ID est 12345 à une fiche d’informations d’entreprise dont l’ID est 67891, l’URL de votre demande sera : /crm/v4/objects/contact/12345/associations/default/company/67891.Pour configurer des associations par défaut en masse, effectuez une demande POST à crm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/default. Dans le corps de la demande, incluez les valeurs objectId des fiches d’informations que vous souhaitez associer.
Pour associer deux fiches d’informations et définir un libellé pour décrire l’association, effectuez une demande PUT à /crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}. Dans le corps de la demande, incluez associationCategory et associationTypeId pour indiquer le type d’association que vous souhaitez créer.Si vous créez des associations sans libellé, vous pouvez utiliser les points de terminaison par défaut décrits dans la section ci-dessus, qui ne nécessitent pas associationCategory ou associationTypeId. Si vous créez des associations avec un libellé, vous pouvez consultez cette liste d’ID de type par défaut ou vous devrez récupérer les types d’association personnalisés entre ces objets.
Pour les relations entre les objets croisés et les libellés jumelés, assurez-vous d’utiliser la méthode typeId qui renvoie à la bonne direction (par exemple : Contact à Entreprise vs Entreprise à Contact, Employé à Responsable ou Responsable à Employé).
Par exemple : pour associer un contact à une transaction à l’aide d’un libellé personnalisé :1. Effectuez une demande GET à /crm/v4/associations/contact/deal/labels.2. Dans la réponse, examinez les valeurs typeId et category du libellé. L’ID sera un nombre (par exemple : 36) et la catégorie sera toujours USER_DEFINED pour les libellés personnalisés.3. Effectuez une demande PUT à /crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId} avec le corps de requête suivant :
Signaler un code incorrect
Copier
Demander à l'IA
/// Example request body[ { "associationCategory": "USER_DEFINED", "associationTypeId": 36 }]
Vous pouvez créer de nouvelles limites d’association ou mettre à jour celles qui existent déjà entre des objets.
Pour créer des limites, effectuez une demande POST à crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/create.
Pour mettre à jour les limites existantes, effectuez une demande POST à crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/update.
Dans le corps de la demande, ajoutez inputs aux éléments suivants :
Paramètre
Description
category
La catégorie de l’association pour laquelle vous définissez une limite, soit HUBSPOT_DEFINED ou USER_DEFINED.
typeId
L’ID numérique du type d’association pour lequel vous souhaitez définir une limite. Consultez cette liste de valeurs typeId par défaut ou récupérez la valeur pour les libellés personnalisés.
maxToObjectIds
Le nombre maximal d’associations autorisé pour le type d’association.
Par exemple, pour définir des limites auxquelles une transaction peut être associée à un maximum de cinq contacts, avec un seul contact intitulé Point de contact pour une transaction, votre demande ressemblerait à ce qui suit :
Pour lire toutes les limites d’association définies, effectuez une demande GET à /crm/v4/associations/definitions/configurations/all. Cela renverra des limites d’association personnalisées définies pour tous les objets.
Pour lire les limites d’association entre deux objets spécifiques, effectuez une demande GET à /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}.
Pour les deux demandes, la réponse renverra les valeurs des associations pour category, typeId, maxToObjectIds et label. Par exemple, si vous récupérez les limites entre les transactions et les contacts, la réponse ressemblera à ceci :
Pour supprimer des limites d’association spécifiques, effectuez une demande POST à /crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purge. Dans le corps de la demande, incluez les valeurs category et typeId des types d’association pour lesquels vous souhaitez supprimer les limites.Par exemple, pour supprimer la limite Point de contact entre les transactions et les contacts, la demande ressemblerait à ceci :
En cas de réussite, vous recevrez une réponse 204 et la limite incluse reviendra au système par défaut (c’est-à-dire que de nombreux contacts peuvent avoir le libellé Point de contact).
Rapport sur l’utilisation fréquente des associations
Il existe des limites techniques au nombre d’associations qu’une fiche d’informations peut avoir. Vous pouvez utiliser l’API d’associations pour récupérer un rapport de fiches d’informations qui approchent ou ont atteint la limite maximale pour les associations.Pour récupérer le rapport, effectuez une demande POST à crm/v4/associations/usage/high-usage-report/{userID}. Le fichier contient des fiches d’informations utilisant 80 % ou plus de leur limite d’association. Par exemple, si une entreprise peut être associée à un maximum de 50 000 contacts, elle sera incluse dans le fichier si elle compte 40 000 contacts associés ou plus. Le fichier sera envoyé à l’e-mail de l’utilisateur dont l’ID a été inclus dans l’URL de la demande. Découvrez comment récupérer des ID utilisateur avec l’API d’utilisateurs.
Les tableaux suivants incluent les valeurs associationTypeId définies par HubSpot qui précisent le type d’association. Les types d’associations varient en fonction des objets inclus et de la direction de l’association (par exemple : Contact à Entreprise est différent de Entreprise à Contact). Si vous créez des objets personnalisés ou des libellés d’association personnalisés, les types d’association associés auront des valeurs typeId uniques que vous devrez récupérer ou localiser dans vos paramètres d’association dans HubSpot.
Les types d’association d’entreprise par défaut incluent un type d’association sans libellé et un type d’association principal. Si une fiche d’informations a plusieurs entreprises associées, une seule peut être l’entreprise principale. Les autres associations peuvent être sans libellé ou avoir des libellés d’association personnalisés.
Si vous utilisez l’API d’associations v1, consultez le tableau ci-dessous pour plus d’informations sur les ID à utiliser lors de l’association de fiches d’informations.
