API du CRM | Propriétés

Run in Postman

Exigences de portée

Utilisez les propriétés pour stocker des informations sur les fiches d’informations du CRM. HubSpot fournit un ensemble de propriétés par défaut pour chaque objet de CRM. Vous pouvez également créer et gérer vos propres propriétés personnalisées dans HubSpot ou à l’aide de l’API de propriétés. Lors de la création de propriétés, il est important de réfléchir à l’architecture de vos données. Dans de nombreux cas, la création de propriétés personnalisées pour les objets standard de HubSpot est la bonne marche à suivre. Cependant, vous devrez parfois créer un objet personnalisé distinct avec son propre ensemble de propriétés.

Propriétés par défaut

Les objets de CRM sont définis par un type principal et un ensemble de properties. Chaque type contient un ensemble de propriétés standards, représenté par une carte de noms et de valeurs. Découvrez-en davantage sur les propriétés par défaut pour différents objets :

Contacts
Entreprises
Entreprises
Tickets
Activités (appels, e-mails, réunions, notes, tâches)
Leads(Sales Hub Pro et Entreprise)

Groupes de propriétés

Les groupes de propriétés sont utilisés pour regrouper des propriétés associées. Toutes les propriétés regroupées apparaîtront les unes à côté des autres sur les fiches d’informations HubSpot. Si votre intégration crée des propriétés d’objets personnalisés, une propriété personnalisée facilitera l’identification de ces données.

Type de propriété et valeurs fieldType

Lorsque vous créez ou mettez à jour des propriétés, les valeurs type et fieldType sont obligatoires. La valeur type détermine le type de propriété, c’est-à-dire une chaîne ou un nombre. La propriété fieldType détermine la façon dont la propriété apparaîtra dans HubSpot ou sur un formulaire, c’est-à-dire en tant que de texte brut, menu déroulant ou sélecteur de dates. Dans le tableau ci-dessous, découvrez les valeurs de propriété type et fieldType disponibles.

`type`	Description	Valeurs `fieldType` valides
`bool`	Champ contenant des options binaires (par exemple : `Yes` ou `No`, `True` ou `False`).	`booleancheckbox`, `calculation_equation`
`enumeration`	Une chaîne représentant un ensemble d’options séparées par un point-virgule.	`booleancheckbox`, `checkbox`, `radio`, `select`, `calculation_equation`
`date`	Une valeur représentant un jour, un mois et une année spécifiques. Les valeurs doivent être représentées au format UTC et peuvent être formatées sous forme de chaînes ISO 8601 ou d’horodatages EPOCH en millisecondes (c.-à-d. minuit UTC).	`date`
`datetime`	Une valeur représentant un jour, un mois, une année et une heure spécifiques. Les valeurs doivent être représentées au format UTC et peuvent être formatées sous forme de chaînes ISO 8601 ou d’horodatages UNIX en millisecondes.	`date`
`string`	Une chaîne de texte brut limitée à 65 536 caractères.	`file`, `text`, `textarea`, `calculation_equation`, `html`, `phonenumber`
`number`	Une valeur numérique contenant des chiffres et au maximum une décimale.	`number`, `calculation_equation`
`object_coordinates`	Valeur de texte utilisée pour référencer d’autres objets HubSpot, utilisée uniquement pour les propriétés internes. Les propriétés de ce type ne peuvent pas être créées ou modifiées et ne sont pas visibles dans HubSpot.	`text`
`json`	Valeur de texte stockée au format JSON, utilisée uniquement pour les propriétés internes. Les propriétés de ce type ne peuvent pas être créées ou modifiées et ne sont pas visibles dans HubSpot.	`text`

Valeurs valides pour fieldType incluent :

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. Découvrez comment ajouter une valeur aux propriétés de case à cocher unique.
`calculation_equation`	Une équation personnalisée qui peut calculer des valeurs en fonction d’autres valeurs de propriété et/ou d’associations. Découvrez comment définir des propriétés calculées.
`checkbox`	Une liste de cases à cocher qui permet à un utilisateur de sélectionner plusieurs options à partir d’un ensemble d’options pour la propriété. Découvrez comment formater des valeurs lors de la mise à jour de propriétés avec plusieurs cases à cocher.
`date`	Une valeur de date, affichée comme un sélecteur de date.
`file`	Permet de télécharger un fichier sur une fiche d’informations ou via un formulaire. Stocke un ID de fichier.
`html`	Une chaîne, restituée dans un format HTML nettoyé, qui permet l’utilisation d’un éditeur de texte enrichi pour la propriété.
`number`	Une chaîne de chiffres ou de nombres sous forme décimale ou en notation scientifique.
`phonenumber`	Une chaîne de texte brut affichée comme un numéro de téléphone formaté.
`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.

Créer une propriété

Pour créer une propriété, effectuez une requête POST à /crm/v3/properties/{objectType}. Dans le corps de votre requête, incluez les champs obligatoires suivants :

groupName : le groupe de propriétés dans lequel la propriété se trouvera.
name : le nom interne de la propriété (par exemple : favorite_food).
label : le nom de la propriété tel qu’il apparaît dans HubSpot (par exemple : plat préféré).
type : le type de propriété.
fieldType : le type de champ de la propriété.

Par exemple, pour créer une propriété de contact appelée Plat préféré, votre requête ressemblera à ceci :

JSON

{
  "groupName": "contactinformation",
  "name": "favorite_food",
  "label": "Favorite Food",
  "type": "string",
  "fieldType": "text"
}

Créer des propriétés d’identifiant unique

Lorsqu’une fiche d’informations est créée dans HubSpot, un ID unique (hs_object_id) est généré automatiquement et doit être considéré comme une chaîne. Ces ID sont uniques pour chaque type d’objet seulement. Un contact et une entreprise peuvent donc avoir le même ID. Pour les contacts et les entreprises, il existe des identifiants uniques supplémentaires, y compris l’adresse e-mail d’un contact (email) et le nom de domaine d’une entreprise (domain). Dans certains cas, vous pouvez créer votre propre propriété d’identifiant unique afin qu’il ne soit pas possible de saisir la même valeur pour plusieurs fiches d’informations. Vous pouvez avoir jusqu’à dix propriétés d’ID unique par objet. Pour créer une propriété nécessitant des valeurs uniques via l’API :

Effectuez une requête POST à /crm/v3/properties/{objectType}.
Dans le corps de votre requête, pour le champ hasUniqueValue, définissez la valeur sur true.

JSON

{
  "groupName": "dealinformation",
  "name": "system_a_unique",
  "label": "Unique ID for System A",
  "hasUniqueValue": true,
  "type": "string",
  "fieldType": "text"
}

Une fois votre propriété d’ID unique créée, vous pouvez l’utiliser dans un appel d’API pour récupérer des fiches d’informations spécifiques. Par exemple, pour récupérer une transaction avec la valeur abc pour la propriété system_a_unique, l’URL votre demande serait : /crm/v3/objects/deals/abc?idProperty=system_a_unique. Vous pouvez ensuite utiliser cette valeur de propriété d’identifiant unique pour identifier et mettre à jour des fiches d’informations spécifiques de la même manière que vous pouvez utiliser hs_object_id, email (contacts) ou domain (entreprises).

Créer des propriétés calculées

Les propriétés calculées définissent une valeur de propriété en fonction d’autres propriétés dans la même fiche d’informations d’objet. Elles sont définies à l’aide d’une formule, qui peut inclure des opérations telles que le minimum, le maximum, le compte, la somme ou la moyenne. Vous pouvez utiliser l’API de propriétés pour lire ou créer des propriétés calculées dans votre compte HubSpot, en utilisant un type de champ calculation_equation et un type number, bool, string ou enumeration. Vous pouvez définir la formule de calcul de la propriété avec le champ calculationFormula.

Remarque :

Les propriétés calculées créées via l’API ne peuvent pas être modifiées dans HubSpot. Vous pouvez modifier ces propriétés uniquement via l’API des propriétés.

Syntaxe des propriétés calculées

À l’aide de calculationFormula, vous pouvez écrire votre formule avec des opérateurs arithmétiques, des opérateurs de comparaison, des opérateurs logiques, des instructions conditionnelles et d’autres fonctions.

Syntaxe littérale

Chaîne littérale : les chaînes constantes peuvent être représentées avec des guillemets simples ('constant') ou des guillemets doubles ("constant").
Nombre littéral : les nombres constants peuvent être n’importe quel nombre réel et peuvent inclure une notation ponctuelle. 1005 et 1.5589 sont tous deux des nombres constants valides.
Booléen littéral : les booléens constants peuvent être true ou false.

Syntaxe de propriété

Variables de propriétés de chaîne : pour qu’une chaîne d’identificateurs soit interprétée comme une propriété de chaîne, elle doit être encadrée dans la fonction string. Par exemple, string(var1) sera interprété comme la valeur de la propriété de chaîne var1.
Variables de propriétés numériques : tous les identifiants seront interprétés comme des variables de propriétés numériques. Par exemple, var1 sera interprété comme la valeur de la propriété numérique var1.
Variables de propriétés booléennes : pour qu’un identifiant soit interprété comme une propriété booléenne, il doit être encadré dans la fonction bool. Par exemple, l’identifiant bool(var1) sera interprété comme la valeur de la propriété booléenne var1.

Remarque :

Remarque : le texte utilisé est sensible à la casse pour tous les types, à l’exception des chaînes. Par exemple, If A ThEn B est exactement identique à if a then b, mais 'a' est différent de 'A'. Les espaces, les onglets et les nouvelles lignes seront utilisés pour la tokenisation, mais seront ignorés.

Opérateurs

Les opérateurs peuvent être utilisés avec des valeurs littérales et de propriété. Pour les opérateurs arithmétiques, vous pouvez utiliser la notation de préfixe pour multiplier et la parenthèse peut être utilisée pour spécifier l’ordre des opérations.

Opérateur	Description	Exemples
`+`	Ajoutez des nombres ou des chaînes de caractères.	`property1 + 100`
`-`	Soustrayez des nombres.	`property1 + 100 - property2`
`*`	Multipliez des nombres.	`10property1` = `10 * property1`
`/`	Divisez des nombres.	`property1 * (100 - property2/(50 - property3))`
`<`	Vérifiez si une valeur est inférieure à une autre. Pris en charge par des propriétés ou des constantes de nombre.	`a < 100`
`>`	Vérifiez si une valeur est supérieure à une autre. Pris en charge par des propriétés ou des constantes de nombre.	`a > 50`
`<=`	Vérifiez si une valeur est inférieure ou égale à une autre. Pris en charge par des propriétés ou des constantes de nombre.	`a <= b`
`>=`	Vérifiez si une valeur est supérieure ou égale à une autre. Pris en charge par des propriétés ou des constantes de nombre.	`b>= c`
`=`	Vérifiez si une valeur est égale à une autre. Pris en charge à la fois par des chiffres et des chaînes.	`(a + b - 100c * 150.652) = 150-230b`
`equals`	Vérifiez si une valeur est égale à une autre. Pris en charge à la fois par des chiffres et des chaînes.	`a + b - 100.2c * 150 equals 150 - 230`
`!=`	Vérifiez si une valeur est différente d’une autre. Pris en charge à la fois par des chiffres et des chaînes.	`string(property1) != 'test_string'`
`or`	Vérifiez si l’une des deux valeurs est exacte.	`a > b or b <= c`
`and`	Vérifiez si les deux valeurs sont vraies.	`bool(a) and bool(c)`
`not`	Vérifiez si aucune des valeurs n’est vraie.	`not (bool(a) and bool(c))`

Fonctions

Les fonctions suivantes sont prises en charge :

Fonction	Description	Exemples
`max`	Aura entre 2 et 100 nombres d’entrées, et renverra le nombre maximum de toutes les entrées.	`max(a, b, c, 100)` ou `max(a, b)`
`min`	Aura entre 2 et 100 nombres d’entrées, et renverra le nombre minimum de toutes les entrées.	`min(a, b, c, 100)` ou `min(a, b)`
`is_present`	Détermine si une expression peut être évaluée.	`is_present(bool(a))`= true si la propriété est booléenne, mais `is_present(bool(a))` = false si la propriété est vide ou non booléenne.
`contains`	A deux chaînes comme entrées et renverra true si la première entrée contient la seconde.	`contains('hello', 'ello')` = `true` tandis que `contains('ello', 'hello')` = false.
`concatenate`	Rejoint une liste de chaînes. La liste des entrées peut aller de 2 à 100.	`concatenate('a', 'b', string(a), string(b))`

Il existe également deux fonctions d’analyse :

number_to_string : tente de convertir l’expression numérique d’entrée en chaîne.
string_to_number : tente de convertir l’expression de chaîne d’entrée en nombre.

Par exemple, "Number of cars: " + num_cars n’est pas une propriété valide car vous ne pouvez pas ajouter une chaîne avec un nombre, mais "Number of cars: " + number_to_string(num_cars) est valide.

Fonctions conditionnelles

Vous pouvez également saisir votre formule avec des fonctions conditionnelles en utilisant if, elseif, endif et else. Par exemple, une fonction conditionnelle pourrait ressembler à : if boolean_expression then statement [elseif expression then statement]* [else statement | endif] où les crochets [a] indiquent que a est facultatif, a|b indique que a ou b fonctionnera, et * signifie 0 ou plus. endif peut être utilisé pour terminer une fonction conditionnelle prématurément, en veillant à ce que l’analyseur puisse identifier à quel élément if le prochain élément elseif appartient.

Exemples de formules

Voici des exemples que vous pouvez utiliser pour vous aider à définir vos propres formules de calcul :

"calculationFormula": "closed - started"

Un exemple plus avancé avec des conditions :

"calculationFormula": "if is_present(hs_latest_sequence_enrolled_date) then
  if is_present(hs_sequences_actively_enrolled_count) an hs_sequences_actively_enrolled_count >= 1 then
    true
  else
    false
else
  ''"

Récupérer des propriétés

Vous pouvez récupérer des informations pour des propriétés individuelles ou toutes les propriétés d’un objet.

Pour récupérer une propriété individuelle, effectuez une requête GET à crm/v3/properties/{object}/{propertyName}. Par exemple, pour récupérer la propriété favorite_food, l’URL de votre requête sera /crm/v3/properties/contacts/favorite_food.
Pour récupérer toutes les propriétés d’un objet, effectuez une requête GET à /crm/v3/properties/{objectType}.

Remarque :

Lors de l’extraction de toutes les propriétés, seules les propriétés non sensibles sont renvoyées par défaut. Pour récupérer des propriétés de données sensibles, incluez le paramètre de requête dataSensitivity avec la valeur sensitive. Pour en savoir plus sur la gestion des données sensibles par API (BETA, Entreprise uniquement).

Mettre à jour ou effacer les valeurs d’une propriété

Pour mettre à jour une valeur de propriété pour une fiche d’informations, effectuez une requête PATCH à crm/v3/objects/{objectType}/{recordId}. Dans le corps de votre requête, incluez les propriétés et leurs valeurs dans un tableau. En savoir plus sur la mise à jour des fiches d’informations via les API objet.

Ajouter des valeurs aux propriétés date et datetime

Les valeurs de temps seront représentées au format ISO 8601 dans les réponses, mais les API HubSpot accepteront l’un ou l’autre des deux formats pour les valeurs de date et d’heure :

Chaîne formatée conformément à la norme ISO 8601 : selon le type de données, il s’agira de l’un de ces deux formats différents :
- Pour les valeurs qui indiquent une date spécifique, le format de date complet sera utilisé : AAAA-MM-JJ (par exemple, 2020-02-29)
- Pour les valeurs qui indiquent une date et une heure spécifiques, les données complètes ainsi que les heures, les minutes, les secondes et une fraction décimale de seconde seront utilisées : AAAA-MM-JJThh:mm:ss.sTZD (par exemple, 2020-02-29T03:30:17.000Z). Toutes les heures sont définies selon le fuseau horaire UTC afin que les valeurs utilisent toujours le désignateur UTC “Z”.
Horodatage UNIX en millisecondes : valeurs d’horodatage en millisecondes, qui sont représentées en temps UTC. Par exemple, la valeur de l’horodatage 1427997766000 se traduit par 2 avr 2015 18:02:46 UTC ou 2 avril 2015, 2:02:46 PM EDT (heure avancée de l’Est).

Il existe deux types de propriétés pour stocker les dates (date et datetime), qui affectent également la façon dont vous formatez les valeurs :

date Les propriétés stockent la date, mais pas l’heure. Les propriétés date affichent la date à laquelle elles sont définies, quelle que soit la définition du fuseau horaire du compte ou de l’utilisateur. Pour les valeurs de propriété date, il est recommandé d’utiliser le format de date complète ISO 8601. Si vous utilisez le format d’horodatage UNIX, vous devez utiliser un horodatage EPOCH en millisecondes (autrement dit, la valeur doit être définie sur minuit UTC pour la date). Par exemple, pour représenter le 1er mai 2015 dans l’un ou l’autre format :
- IOS 8601 : 2015-05-01
- Horodatage UNIX en millisecondes : 1430438400000
Les propriétés datetime stockent à la fois la date et l’heure. L’un ou l’autre format d’horodatage sera accepté. Dans HubSpot, les propriétés datetime sont affichées en fonction du fuseau horaire de l’utilisateur. Ainsi, la valeur sera convertie selon le fuseau horaire local de l’utilisateur.

Ajouter des valeurs à des propriétés de case à cocher

Lors de la mise à jour des valeurs pour les propriétés de case à cocher d’une fiche d’informations, formatez les valeurs selon les modalités suivantes :

Propriété de case à cocher booléenne : pour afficher comme Oui ou cochée dans HubSpot, votre valeur doit être true. Pour afficher comme Non ou non coché dans HubSpot, votre valeur doit être false.
Propriété de case à cocher à sélection multiple : pour ajouter ou joindre des valeurs à une propriété à plusieurs cases à cocher, ajoutez un point-virgule avant la première valeur et séparez les valeurs avec des points-virgules sans espace au milieu. Si la propriété possède une valeur existante, le point-virgule principal ajoutera les valeurs au lieu de les remplacer. Par exemple, un contact a la valeur existante DECISION_MAKER pour la propriété hs_buying_role. Pour ajouter des valeurs supplémentaires sans remplacer la valeur existante, votre requête ressemblera à ceci :

JSON

{
  "properties": {
    "hs_buying_role": ";BUDGET_HOLDER;END_USER"
  }
}

Attribuer des propriétaires de fiche d’informations à des propriétés d’utilisateur

Lorsque vous attribuez des utilisateurs à des fiches d’informations de CRM via l’API, votre valeur doit être l’élément id du propriétaire de l’utilisateur, que vous pouvez trouver dans les paramètres de votre propriété ou via l’API des propriétaires. Par exemple, pour affecter un utilisateur en tant que propriétaire d’un contact, effectuez une requête PATCH à crm/v3/objects/contacts/{contactId}, avec le corps { "properties":{ "hubspot_owner_id": "41629779"}}.

Effacer une valeur de propriété

Vous pouvez effacer la valeur d’une propriété d’objet via l’API en définissant la valeur de la propriété sur une chaîne de caractères vide. Par exemple, pour effacer le firstname d’un objet de contact, envoyez une requête PATCH à /crm/v3/objects/contacts/{contactId} avec le corps { "properties": { "firstname": ""}}.

Account & Settings

Gestion des applications

Authentification

Automatisation

CMS

Préférences de communication

Conversations

CRM

Événements

Fichiers

Marketing

Planificateur

Webhooks

API du CRM | Propriétés

Run in Postman

Propriétés par défaut

Groupes de propriétés

Type de propriété et valeurs fieldType

Créer une propriété

Créer des propriétés d’identifiant unique

Créer des propriétés calculées

Remarque :

Syntaxe des propriétés calculées

Syntaxe littérale

Syntaxe de propriété

Remarque :

Opérateurs

Fonctions

Fonctions conditionnelles

Exemples de formules

Récupérer des propriétés

Remarque :

Mettre à jour ou effacer les valeurs d’une propriété

Ajouter des valeurs aux propriétés date et datetime

Ajouter des valeurs à des propriétés de case à cocher

Attribuer des propriétaires de fiche d’informations à des propriétés d’utilisateur

Effacer une valeur de propriété

Run in Postman

​Propriétés par défaut

​Groupes de propriétés

​Type de propriété et valeurs fieldType

​Créer une propriété

​Créer des propriétés d’identifiant unique

​Créer des propriétés calculées

​Remarque :

​Syntaxe des propriétés calculées

​Syntaxe littérale

​Syntaxe de propriété

​Remarque :

​Opérateurs

​Fonctions

​Fonctions conditionnelles

​Exemples de formules

​Récupérer des propriétés

​Remarque :

​Mettre à jour ou effacer les valeurs d’une propriété

​Ajouter des valeurs aux propriétés date et datetime

​Ajouter des valeurs à des propriétés de case à cocher

​Attribuer des propriétaires de fiche d’informations à des propriétés d’utilisateur

​Effacer une valeur de propriété

Propriétés par défaut

Groupes de propriétés

Type de propriété et valeurs fieldType

Créer une propriété

Créer des propriétés d’identifiant unique

Créer des propriétés calculées

Remarque :

Syntaxe des propriétés calculées

Syntaxe littérale

Syntaxe de propriété

Remarque :

Opérateurs

Fonctions

Fonctions conditionnelles

Exemples de formules

Récupérer des propriétés

Remarque :

Mettre à jour ou effacer les valeurs d’une propriété

Ajouter des valeurs aux propriétés date et datetime

Ajouter des valeurs à des propriétés de case à cocher

Attribuer des propriétaires de fiche d’informations à des propriétés d’utilisateur

Effacer une valeur de propriété