Produits pris en charge
Exige l'un des produits suivants ou un produit supérieur.
Marketing HubMarketing HubEntreprise
Sales HubSales HubEntreprise
Service HubService HubEntreprise
Content HubContent HubEntreprise
Dernière modification : 28 août 2025

Run in Postman

 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 :

​
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 requête de schéma dans l’onglet Schéma d’objet en haut de cet article. Vous pouvez également consulter un exemple de requête ci-dessous. Pour créer le schéma d’objet personnalisé, effectuez une requête POST à crm/v3/schemas. Dans le corps de la requête, 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 nom 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 requête 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 requête 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é.
typeDescriptionValeurs fieldType valides
enumerationUne chaîne représentant un ensemble d’options, séparées par un point-virgule.booleancheckbox, checkbox, radio, select
dateUne valeur au format ISO 8601 représentant un jour, un mois et une année spécifiques.date
dateTimeUne 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
stringUne chaîne de texte brut limitée à 65 536 caractères.file, text, textarea
numberUne valeur numérique contenant des chiffres et au maximum une décimale.number
fieldTypeDescription
booleancheckboxUne 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.
checkboxUne liste de cases à cocher qui permet à un utilisateur de sélectionner plusieurs options à partir d’un ensemble d’options pour la propriété.
dateUne valeur de date, affichée comme un sélecteur de date.
filePermet de charger un fichier dans un formulaire. Stocké et affiché en tant que lien d’URL vers le fichier.
numberUne chaîne de chiffres ou de nombres sous forme décimale ou en notation scientifique.
radioUne 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.
selectUne entrée déroulante qui permet aux utilisateurs de sélectionner l’une des options autorisées pour la propriété.
textUne chaîne de texte brut, affichée dans une entrée de texte sur une seule ligne.
textareaUne 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 requête 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 : 

"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 requête GET à /crm/v3/schemas. Pour récupérer un objet personnalisé spécifique, effectuez une requête 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 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 requête peut ressembler à ce qui suit :

​
Récupérer des fiches d’informations d’objets personnalisés

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 requête 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 :
ParamètreDescription
propertiesUne 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.
propertiesWithHistoryUne 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.
associationsUne 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 une requête 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 requête, 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 id dans la requête 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 requête peut ressembler à ce qui suit : 
{
  "properties": ["petname"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

{
  "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 requête peut ressembler à ceci : 
{
  "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 requête PATCH à https://api.hubapi.com/crm/v3/schemas/{objectTypeId}. Une fois votre objet personnalisé défini :
  • Le nom et les libellés de l’objet (singulier et pluriel) ne peuvent pas être modifiés.
  • Les propriétés requiredProperties, searchableProperties, primaryDisplayProperty et secondaryDisplayProperties peuvent être modifiés 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 requête 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 : 
{
  "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 requête 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 requête 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 requêtes 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. Remarques : 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 requête POST à /crm/v3/schemas avec le corps de la requête suivant : 
{
  "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 s’assure de noter le champ {objectTypeId} du nouvel objet, car il l’utilisera plus tard pour récupérer et mettre à jour l’objet. Ils peuvent également utiliser la valeur {fullyQualifiedName} s’ils le préfèrent.

​
Création d’un enregistrement de l’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 requête POST à /crm/v3/objects/2-3465404 avec le corps suivant : 
{
  "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 : 
{
  "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 requête 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 requête 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 requête GET à crm/v3/schemas/{objectType}. Par exemple, avec l’ID 51 de contact 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 requête 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, il créera une nouvelle association en effectuant une requête POST à /crm/v3/schemas/2-3465404/associations avec le corps suivant : 
{
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "ticket",
  "name": "car_to_ticket"
}
La réponse pour cet appel d’API se présente comme suit : 
{
  "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 requête POST à /crm/v3/properties/2-3465404 avec le corps de requête suivant : 
{
  "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 : 
{
  "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 requête PATCH à /crm/v3/schemas/2-3465404 avec le corps suivant : 
{
  "secondaryDisplayProperties": ["maintenance_package"]
}
La réponse pour cet appel d’API se présente comme suit : 
{
  "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 :
Capture d'écran du 06/03/2020 à 11.08.41
À 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é.