Objets personnalisés

Vous pouvez créer, lire et mettre à jour des objets personnalisés via l'une des méthodes d'authentification suivantes :

• OAuth
• Jetons d'accès d'application privée

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.

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.

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é.

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ément

  fullyQualifiedName d'un objet dans son schéma, qui est dérivé de p{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ètre idProperty 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ètre idProperty.

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 et secondaryDisplayProperties 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 :

1. la création d'un schéma d'objet personnalisé ;
2. la création d'une fiche d'informations d'objet personnalisé ;
3. l'association d'une fiche d'informations d'objet personnalisé à un contact HubSpot ;
4. la création d'une nouvelle définition d'association entre l'objet personnalisé et le ticket HubSpot ;
5. la création d'une nouvelle définition de propriété ;
6. 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 : 

1. État (neuf ou occasion) : énumération
2. Date de réception chez le concessionnaire : date
3. Année : nombre
4. Marque : chaîne
5. Modèle : chaîne
6. NIV : chaîne (valeur unique)
7. Couleur : chaîne
8. Kilométrage : nombre
9. Prix : nombre
10. 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.

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 :

Une fois la fiche d'informations créée, il peut utiliser la valeur id pour associer ultérieurement le véhicule à un contact existant.

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 :

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 :

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é.