Objets personnalisés
Marketing Hub
- Enterprise
Sales Hub
- Enterprise
Service Hub
- Enterprise
CMS Hub
- Enterprise
Operations Hub
- Enterprise
Chaque compte HubSpot présente des objets CRM standard : contacts, entreprises, transactions et tickets. Pour représenter et organiser vos données de CRM en fonction des besoins de votre entreprise, vous pouvez également créer des objets personnalisés. Vous pouvez créer un objet personnalisé dans HubSpot ou utiliser l'API d'objets personnalisés pour définir des objets personnalisés, des propriétés et des associations avec d'autres objets CRM.
Ci-dessous, découvrez comment créer et gérer des objets personnalisés via l'API, et profitez d'un exemple qui explique comment créer un objet personnalisé.
Pour en savoir plus sur la création d'objets personnalisés, consultez les articles suivants sur le blog pour les développeurs de HubSpot :
Remarque : les objets personnalisés sont spécifiques à chaque compte et, en fonction de votre abonnement, le nombre d'objets personnalisés que vous pouvez créer est limité. Découvrez-en davantage sur vos limites dans le catalogue des produits et services de HubSpot.
Vous pouvez créer, lire et mettre à jour des objets personnalisés via l'une des méthodes d'authentification suivantes :
Remarque : À compter du 30 novembre 2022, les clés d'API HubSpot sont obsolètes et ne sont plus prises en charge. L'utilisation continue des clés d'API HubSpot constitue un risque pour la sécurité de votre compte et de vos données. Pendant cette phase, HubSpot peut désactiver votre clé à tout moment.
Veillez plutôt à vous authentifier à l'aide d'un jeton d'accès d'application privée ou d'OAuth. Découvrez-en davantage sur cette modification et sur la migration d'une intégration de clé d'API pour utiliser une application privée à la place.
Pour créer un objet personnalisé, vous devez d'abord définir le schéma d'objet. Le schéma inclut le nom de l'objet, les propriétés et les associations à d'autres objets de CRM. Vous pouvez trouver les détails complets de la demande de schéma dans l'onglet Schéma d'objet en haut de cet article. Vous pouvez également consulter un exemple de demande ci-dessous.
Pour créer le schéma d'objet personnalisé, effectuez une demande POST
à crm/v3/schemas
. Dans le corps de la demande, incluez les définitions de votre schéma d'objet, y compris son nom, ses propriétés et ses associations.
Lorsque vous nommez votre objet personnalisé, tenez compte des points suivants :
- Une fois que vous créez un objet, le nom et le libellé de l'objet ne peuvent pas être modifiés.
- Le name peut uniquement contenir des lettres, des chiffres et des tirets bas.
- Le premier caractère du nom doit être une lettre.
- Les longs libellés peuvent être coupés dans certaines parties du produit.
Ci-dessous, consultez les définitions requises pour les propriétés et les associations de l'objet.
Les propriétés que vous définissez dans le corps de la demande seront utilisées pour stocker des informations sur les fiches d'informations d'objets personnalisés individuelles.
Remarque : vous pouvez avoir jusqu'à 10 propriétés de valeur uniques pour chaque objet personnalisé dans votre compte HubSpot.
Vous utiliserez vos propriétés définies pour remplir les champs suivants basés sur les propriétés :
- requiredProperties : les propriétés requises lors de la création d'une nouvelle fiche d'informations d'objet personnalisé.
- searchableProperties : les propriétés qui sont indexées pour la recherche dans HubSpot.
- primaryDisplayProperty : la propriété utilisée pour nommer des fiches d'informations d'objets personnalisés.
- secondaryDisplayProperties : les propriétés qui apparaissent sur les fiches d'informations individuelles sous primaryDisplayProperty.
- La première propriété répertoriée dans
secondaryDisplayProperties
sera également ajoutée en tant que quatrième filtre sur la page index des objets s'il s'agit d'un des types de propriété suivants :string
number
enumeration
boolean
datetime
- Pour supprimer une propriété d'affichage de l'interface utilisateur, vous devez d'abord supprimer la propriété, puis la recréer.
- La première propriété répertoriée dans
Par défaut, lors de la création de propriétés durant la demande de schéma, le type
de propriété est défini sur string
, et le fieldType
est défini sur text
. Vous trouverez ci-dessous les valeurs que vous pouvez utiliser pour créer différents types de propriété.
type |
Description | Valeurs fieldType valides |
---|---|---|
enumeration |
Une chaîne représentant un ensemble d'options, séparées par un point-virgule. | booleancheckbox , checkbox , radio , select |
date |
Une valeur au format ISO 8601 représentant un jour, un mois et une année spécifiques. | date |
dateTime |
Une valeur au format ISO 8601 représentant un jour, un mois, une année et une heure spécifiques. L'application HubSpot n'affichera pas l'heure. | date |
string |
Une chaîne de texte brut limitée à 65 536 caractères. | file , text , textarea |
number |
Une valeur numérique contenant des chiffres et au maximum une décimale. | number |
fieldType |
Description |
---|---|
booleancheckbox |
Une entrée qui permet aux utilisateurs de sélectionner Oui ou Non. Lorsque vous l'utilisez dans un formulaire, cette case sera affichée comme une case à cocher unique. |
checkbox |
Une liste de cases à cocher qui permettent à un utilisateur de sélectionner plusieurs options à partir d'un ensemble d'options pour la propriété. |
date |
Une valeur de date, affichée comme un sélecteur de date. |
file |
Permet de charger un fichier dans un formulaire. Stocké et affiché en tant que lien d'URL vers le fichier. |
number |
Une chaîne de chiffres ou de nombres sous forme décimale ou en notation scientifique. |
radio |
Une entrée qui permet aux utilisateurs de sélectionner l'une des options autorisées pour la propriété. Lorsque vous l'utilisez dans un formulaire, elle sera affichée comme un ensemble de cases d'option. |
select |
Une entrée déroulante qui permet aux utilisateurs de sélectionner l'une des options autorisées pour la propriété. |
text |
Une chaîne de texte brut, affichée dans une entrée de texte sur une seule ligne. |
textarea |
Une chaîne de texte brut, affichée dans une entrée de texte sur plusieurs lignes. |
Associations
HubSpot associera automatiquement un objet personnalisé aux objets d'e-mail, de réunion, de note, de tâche, d'appel et de conversation. Vous pouvez également associer votre objet personnalisé à d'autres objets HubSpot standard ou à d'autres objets personnalisés.
Lors de la création d'associations via la demande de création de schéma, identifiez les objets standard en utilisant leurs noms et les objets personnalisés en utilisant leur valeur objectTypeId
. Par exemple :
Pour récupérer tous les objets personnalisés, effectuez une demande GET
à/crm/v3/schemas
.
Pour récupérer un objet personnalisé spécifique, effectuez une demande GET
à l'un des points de terminaison suivants :
/crm/v3/schemas/{objectTypeId}
/crm/v3/schemas/p_{object_name}
/crm/v3/schemas/{fullyQualifiedName}
. Vous pouvez trouver l'élémentfullyQualifiedName
d'un objet dans son schéma, qui est dérivé dep{portal_id}_{object_name}
. Vous pouvez trouver l'identifiant de portail de votre compte à l'aide de l'API d'informations de compte.
Par exemple, pour un compte avec un ID 1234
et un objet nommé lender
, l'URL de votre demande peut ressembler à ce qui suit :
https://api.hubapi.com/crm/v3/schemas/2-3465404
https://api.hubapi.com/crm/v3/schemas/p_lender
https://api.hubapi.com/crm/v3/schemas/p1234_lende
Vous pouvez également récupérer les fiches d'informations d'un objet personnalisé.
- Pour récupérer une fiche d'informations spécifique par sa valeur d'ID, effectuez une demande
GET
àcrm/v3/objects/{objectType}/{recordId}
. - Pour récupérer plusieurs fiches d'informations, effectuez unedemande
POST
àcrm/v3/objects/{objectType}/batch/read
. Dans votre demande, vous pouvez récupérer les fiches d'informations selon leur ID (hs_object_id
) ou une propriété d'identifiant unique personnalisée. Par défaut, les valeurs d'identifiant
dans la demande font référence à l'ID de fiche d'informations, de sorte que le paramètreidProperty
n'est pas requis lors de la récupération par ID de fiche d'informations. Pour utiliser une propriété de valeur unique personnalisée, vous devez inclure le paramètreidProperty
.
Par exemple, pour récupérer un lot fiches d'informations d'objet personnalisé, votre demande peut ressembler à ce qui suit :
Pour mettre à jour le schéma d'un objet, effectuez une demande PATCH
à https://api.hubapi.com/crm/v3/schemas/{objectTypeId}
.
Une fois votre objet personnalisé défini :
- Le nom et les libellés (singulier et pluriel) ne peuvent pas être modifiés.
- Les propriétés
requiredProperties
,searchableProperties
,primaryDisplayProperty
etsecondaryDisplayProperties
peuvent être modifiées en mettant à jour le schéma de l'objet. Pour définir une nouvelle propriété en tant que propriété obligatoire, consultable ou d'affichage, vous devez créer la propriété avant de mettre à jour le schéma. - Vous pouvez créer et modifier des propriétés d'objets personnalisés dans HubSpot ou via l'API de propriétés.
Mettre à jour des associations
Pour ajouter d'autres associations d'objets à votre objet personnalisé, effectuez une demande POST
à /crm/v3/schemas/{objectTypeId}/associations
.
Vous ne pouvez associer votre objet personnalisé qu'à des objets HubSpot standard (par exemple, contact, entreprise, transaction ou ticket) ou d'autres objets personnalisés. Dans le champ toObjectTypeId
, identifiez les objets personnalisés par leur valeur objectTypeId
et les objets standard par leur nom. Par exemple :
Vous ne pouvez supprimer un objet personnalisé qu'après la suppression de toutes les instances d'objet de ce type. Pour supprimer un objet personnalisé, effectuez une demande DELETE
à /crm/v3/schemas/{objectType}
.
Si vous devez créer un nouvel objet personnalisé portant le même nom que l'objet supprimé, vous devez supprimer le schéma en effectuant une demande DELETE
à /crm/v3/schemas/{objectType} ?archived=true
. Vous ne pouvez supprimer un type d'objet personnalisé qu'après la suppression de toutes les instances d'objet de ce type, associations et propriétés d'objet personnalisé.
Cet exemple explique comment créer un objet personnalisé. Pour de plus amples détails sur les demandes affichées, consultez l'onglet Définition d'objet en haut de l'article.
Cette section aborde :
- la création d'un schéma d'objet personnalisé ;
- la création d'une fiche d'informations d'objet personnalisé ;
- l'association d'une fiche d'informations d'objet personnalisé à un contact HubSpot ;
- la création d'une nouvelle définition d'association entre l'objet personnalisé et le ticket HubSpot ;
- la création d'une nouvelle définition de propriété ;
- la mise à jour du schéma d'objet (c.-à-d.
secondaryDisplayProperties
) avec la nouvelle propriété.
Objectif : un concessionnaire automobile appelé CarSpot souhaite stocker son inventaire dans HubSpot à l'aide d'un objet personnalisé. Pour suivre la propriété et les achats des véhicules, il associe ces derniers à des fiches d'informations de contact. Parallèlement, il suivra également l'entretien des véhicules à l'aide de tickets HubSpot et de propriétés personnalisées.
Création du schéma d'objet
CarSpot doit créer un schéma d'objet qui peut représenter les attributs suivants en tant que propriétés :
- État (neuf ou occasion) : énumération
- Date de réception chez le concessionnaire : date
- Année : nombre
- Marque : chaîne
- Modèle : chaîne
- NIV : chaîne (valeur unique)
- Couleur : chaîne
- Kilométrage : nombre
- Prix : nombre
- Notes : chaîne
Le concessionnaire ajoutera également une définition expliquant comment utiliser l'objet et définira une association entre l'objet personnalisé et l'objet de contact standard afin d'associer des véhicules à des acheteurs potentiels.
Une fois le modèle de données finalisé, le concessionnaire créera le schéma d'objet en effectuant une demande POST
à /crm/v3/schemas
avec le corps suivant : Tout copier.
Après avoir créé le schéma de l'objet, CarSpot veille à noter le champ {objectTypeId}
du nouvel objet, car il l'utilisera pour ultérieurement récupérer et mettre à jour l'objet. CarSpot peut également utiliser la valeur {fullyQualifiedName}
, le cas échéant.
Création d'une fiche d'informations d'objet personnalisé
Une fois l'objet personnalisé créé, CarSpot peut désormais créer des fiches d'informations d'objet pour chaque véhicule de son inventaire.
Le concessionnaire créera son premier véhicule en effectuant une demande POST
à /crm/v3/objects/2-3465404
avec le corps suivant :
La réponse pour cet appel d'API se présente comme suit : Tout copier.
Une fois la fiche d'informations créée, il peut utiliser la valeur id
pour associer ultérieurement le véhicule à un contact existant.
Pour récupérer ultérieurement cette fiche d'informations avec des propriétés spécifiques, il peut effectuer une demande GET
à https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model
Association de la fiche d'informations d'objet personnalisé à une autre fiche d'informations
Vous pouvez utiliser l'ID de fiche d'informations de la nouvelle voiture (181308
) et l'ID d'une autre fiche d'informations pour associer une fiche d'informations d'objet personnalisé à une fiche d'informations d'un autre objet.
Pour créer une association, effectuez une demande PUT
à /crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}
. Si la relation d'objet est déjà définie, pour déterminer la valeur associationType
, effectuez une demande GET
à crm/v3/schemas/{objectType}
.
Par exemple, avec l'ID de contact 51
et le type d'association 75
, CarSpot peut associer la fiche d'informations de la voiture à un contact. Utilisant les ID ci-dessus, l'URL de la demande sera créée comme suit :
https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75
Définition d'une nouvelle association
CarSpot souhaite maintenant commencer à suivre les services après-vente pour ses véhicules. Pour ce faire, il utilisera les tickets HubSpot pour enregistrer tout entretien effectué.
Pour autoriser les associations entre les véhicules et les tickets, ils créera une nouvelle association en effectuant une demande POST
à /crm/v3/schemas/2-3465404/associations
avec le corps suivant :
La réponse pour cet appel d'API se présente comme suit : Tout copier.
Lors de la création d'une association entre deux objets personnalisés, spécifiez les objets personnalisés par leur objectTypeId dans le champ toObjectTypeId. Pour les objets standard, vous pouvez les identifier par leur nom ou utiliser les valeurs suivantes :
- Contact : 0-1
- Entreprise : 0-2
- Transaction : 0-3
- Ticket : 0-5
Définition d'une nouvelle propriété
Alors qu'il continue de suivre les entretiens, CarSpot voit une opportunité de regrouper ses services d'entretien dans des forfaits. Pour suivre ces forfaits d'entretien sur des fiches d'informations de véhicule individuelles, il créera une nouvelle propriété d'énumération contenant les forfaits disponibles.
Pour définir une nouvelle propriété, il effectuera une demande POST
à /crm/v3/properties/2-3465404
avec le corps suivant :
La réponse pour cet appel d'API se présente comme suit : Tout copier.
Une fois que cette propriété est créée, il souhaite que cette propriété apparaisse dans la barre latérale de chaque fiche d'informations de véhicule afin que les informations soient facilement disponibles pour ses commerciaux et mécaniciens. Pour cela, il ajoutera la propriété à secondaryDisplayProperties
en effectuant une demande PATCH
à /crm/v3/schemas/2-3465404 avec
le corps suivant :
La réponse pour cet appel d'API se présente comme suit : Tout copier.
Désormais, lorsqu'un mécanicien ouvre une fiche d'informations de contact qui contient un véhicule associé, la propriété s'affichera dans la carte d'objet personnalisé dans la barre latérale :
À mesure que CarSpot utilise HubSpot, il trouvera probablement des moyens d'affiner et d'étendre cet objet personnalisé et plus encore à l'aide de l'API de HubSpot. Il pourra même décider de créer des pages dynamiques à l'aide de ses données d'objet personnalisé.
Merci d'avoir partagé votre avis.