Objets personnalisés

PrésentationObjetsSchéma d'objet
APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise
  • Content 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.

Méthodes d'authentification

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.

Créer un objet personnalisé

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. 

Propriétés

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.
    custom-object-secondary-display-properties0
    • 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
        custom-object-dashboard-filter0
    • 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é.

Valeurs valides pour type
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
Valeurs valides pour fieldType 
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 : 

// Example associatedObjects array "associatedObjects": [ "CONTACT", "COMPANY", "TICKET", "DEAL", "2-3453932" ]

Récupérer des objets personnalisés existants

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 :

Récupérer des fiches d'informations personnalisées

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 ce point de terminaison, vous pouvez inclure les paramètres suivants dans l'URL de la requête : 

Use this table to describe parameters / fields
ParameterDescription
properties

Une liste séparée par des virgules des propriétés à renvoyer dans la réponse. Si la fiche d'informations d'objet personnalisé demandée n'a pas de valeur pour une propriété, elle n'apparaîtra pas dans la réponse.

propertiesWithHistory

Une liste séparée par des virgules des propriétés actuelles et historiques à renvoyer dans la réponse. Si la fiche d'informations d'objet personnalisé demandée n'a pas de valeur pour une propriété, elle n'apparaîtra pas dans la réponse.

associations

Une liste séparée par des virgules des objets pour lesquels récupérer les ID associés. Les associations spécifiées qui n'existent pas ne seront pas renvoyées dans la réponse. Découvrez-en davantage sur l'API des associations.
  • Pour récupérer plusieurs fiches d'informations, effectuez unedemande POST à crm/v3/objects/{objectType}/batch/read. Le point de terminaison du lot ne peut pas récupérer les associations. Découvrez comment lire par lots les associations avec l'API des associations.

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 :

///Example request body for record ID { "properties": [ "petname" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }
///Example request body for unique value property { "properties": [ "petname" ], "idProperty": "uniquepropertyexample", "inputs": [ { "id": "abc" }, { "id": "def" } ] }
Pour récupérer des fiches d'informations d'objets personnalisés avec des valeurs actuelles et historiques pour une propriété, votre demande peut ressembler à ceci :
///Example request body for record ID (current and historical values) { "propertiesWithHistory": [ "pet_owner" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

Mettre à jour des objets personnalisés existants

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 :

// Example association request body { "fromObjectTypeId": "2-3444025", "toObjectTypeId": "ticket", "name": "cat_to_ticket" }

Supprimer un objet personnalisé

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

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

// Example POST request to https://api.hubspot.com/crm/v3/schemas { "name": "cars", "description": "Cars keeps track of cars currently or previously held in our inventory.", "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "properties": [ { "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "options": [ { "label": "New", "value": "new" }, { "label": "Used", "value": "used" } ] }, { "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date" }, { "name": "year", "label": "Year", "type": "number", "fieldType": "number" }, { "name": "make", "label": "Make", "type": "string", "fieldType": "text" }, { "name": "model", "label": "Model", "type": "string", "fieldType": "text" }, { "name": "vin", "label": "VIN", "type": "string", "hasUniqueValue": true, "fieldType": "text" }, { "name": "color", "label": "Color", "type": "string", "fieldType": "text" }, { "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number" }, { "name": "price", "label": "Price", "type": "number", "fieldType": "number" }, { "name": "notes", "label": "Notes", "type": "string", "fieldType": "text" } ], "associatedObjects": [ "CONTACT" ] }

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 :

// Example POST request to https://api.hubspot.com/crm/v3/objects/2-3465404 { "properties": { "condition": "used", "date_received": "1582416000000", "year": "2014", "make": "Nissan", "model": "Frontier", "vin": "4Y1SL65848Z411439", "color": "White", "mileage": "80000", "price": "12000", "notes": "Excellent condition. No accidents." } }

La réponse pour cet appel d'API se présente comme suit : Tout copier.

// Example response body { "id": "181308", "properties": { "color": "White", "condition": "used", "make": "Nissan", "mileage": "80000", "model": "Frontier", "vin": "4Y1SL65848Z411439", "notes": "Excellent condition. No accidents.", "price": "12000", "year": "2014", "date_received": "1582416000000" }, "createdAt": "2020-02-23T01:44:11.035Z", "updatedAt": "2020-02-23T01:44:11.035Z", "archived": false }

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 :

// Example POST request to https://api.hubspot.com/crm/v3/schemas/2-3465494/associations { "fromObjectTypeId": "2-3465404", "toObjectTypeId": "ticket", "name": "car_to_ticket" }

La réponse pour cet appel d'API se présente comme suit : Tout copier.

// Example response { "id": "121", "createdAt": "2020-02-23T01:52:12.893826Z", "updatedAt": "2020-02-23T01:52:12.893826Z", "fromObjectTypeId": "2-3465404", "toObjectTypeId": "0-5", "name": "car_to_ticket" }

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 :

// Example POST request to https://api.hubspot.com/crm/v3/properties/2-3465404 { "groupName": "car_information", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Basic", "value": "basic" }, { "label": "Oil change only", "value": "oil_change_only" }, { "label": "Scheduled", "value": "scheduled" } ] }

La réponse pour cet appel d'API se présente comme suit : Tout copier.

// Example response { "updatedAt": "2020-02-23T02:08:20.055Z", "createdAt": "2020-02-23T02:08:20.055Z", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "Basic", "value": "basic", "displayOrder": -1, "hidden": false }, { "label": "Oil change only", "value": "oil_change_only", "displayOrder": -1, "hidden": false }, { "label": "Scheduled", "value": "scheduled", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }

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 : 

// Example PATCH request to https://api.hubspot.com/crm/v3/schemas/2-3465404 { "secondaryDisplayProperties": [ "maintenance_package" ] }

La réponse pour cet appel d'API se présente comme suit : Tout copier.

// Example response { "id": "3465404", "createdAt": "2020-02-23T01:24:54.537Z", "updatedAt": "2020-02-23T02:12:24.175874Z", "labels": { "singular": "Car", "plural": "Cars" }, "requiredProperties": [ "year", "model", "vin", "make" ], "searchableProperties": [ "year", "model", "vin", "make" ], "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "maintenance_package" ], "portalId": 1234567, "name": "car" }

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 :

Screen Shot 2020-03-06 at 11.08.41 AM

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

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