Dernière modification : 11 septembre 2025
Après avoir défini un schéma de type d’événement et récupéré son fullyQualifiedName, vous pouvez envoyer des données d’occurrence d’événement via l’API d’événements de l’application. Lors de l’envoi de données d’événement, vous devrez respecter le schéma que vous avez créé précédemment. Les requêtes qui ne correspondent pas au schéma échoueront à être validées et ne seront pas capturées par l’application.

​
Envoi d’occurrence d’événements

Pour envoyer une occurrence d’événement unique, effectuez une requête POST à /integrators/timeline/v4/events.Dans le corps de la requête, incluez les données d’événements suivant le schéma défini pour le type d’événement ainsi que la valeur fullyQualifiedName dans un champ eventTypeName.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Les champs marqués par * sont requis.

ChampTypeDescription
eventTypeName*Chaînele nom entièrement qualifié du type d’événement, que vous utiliserez pour identifier l’événement via l’API. Cette valeur est automatiquement définie par HubSpot et peut être obtenue via l’API après la création du type d’événement. Cette valeur ne peut pas être modifiée après la création.
objectId*Chaînel’ID de la fiche d’informations de CRM à associer à l’événement. Ce champ peut être utilisé pour tous les types de fiches d’informations de CRM et constitue l’identifiant recommandé. Découvrez-en davantage sur l’association des fiches d’informations CRM.
emailChaînepour l’association de contact, vous pouvez fournir l’adresse e-mail du contact à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
utkChaînepour l’association de contacts, vous pouvez fournir le jeton utilisateur d’un contact existant à associer. Découvrez-en davantage sur l’association des fiches d’informations CRM.
domainChaîneincluez ce champ en plus de objectId pour définir la valeur de propriété de l’entreprise domain. Découvrez-en davantage sur l’association des fiches d’informations CRM.
timestampChaînedéfinit l’heure de l’occurrence de l’événement (format ISO 8601). Si ce champ n’est pas renseigné, HubSpot utilisera par défaut l’horodatage de l’envoi des données d’occurrence d’événement.
propertiesObjetpaires clé-valeur des noms et valeurs des propriétés que vous avez configuré pour le type d’événement. Découvrez-en davantage sur les propriétés d’événement.
extraDataObjetdes informations supplémentaires qui seront disponibles pour les modèles de rendu de chronologie. Doit être au format JSON valide.
timelineIFrameObjetune fois incluse, la carte de chronologie comprendra un lien hypertexte qui permet aux utilisateurs d’ouvrir le contenu lié dans un iframe. Découvrez-en davantage sur l’utilisation des iframes.
idChaîneun identifiant unique pour l’occurrence de l’événement. Doit être unique dans le type d’événement. Si ce champ n’est pas renseigné, HubSpot générera un GUID aléatoire. Lorsque plusieurs événements ont le même ID, le premier sera accepté et tous les autres seront rejetés.

​
Association des fiches d’informations CRM

Chaque événement doit être associé à une fiche d’informations CRM, le type d’objet CRM étant défini par le schéma de type d’événement. L’API des événements de l’application comprend plusieurs champs pour associer les données d’occurrence d’événement aux fiches d’informations CRM. Pour tous les objets CRM pris en charge, il est recommandé d’utiliser le champ objectId. Cependant, dans certaines situations, vous souhaiterez peut-être utiliser les autres champs.
  • utk/email : si vous ne connaissez pas l’ID du contact, utilisez le champ utk et/ou email pour l’identification. Fournir ces deux identifiants vous permet également de créer et de mettre à jour des contacts. Par exemple :
    • Si utk correspond à un contact existant, mais que l’email ne correspond pas, HubSpot mettra à jour le contact (par utk) avec la nouvelle adresse e-mail.
    • Si aucun objectId n’est fourni, l’occurrence de l’événement sera associée à un contact existant correspondant à utk/email, ou HubSpot créera un nouveau contact si aucune correspondance n’est trouvée.
    • Notez que le utk seul ne peut pas créer de nouveaux contacts. Vous devez toujours inclure l’email avec utk pour garantir une bonne association.
  • domain : pour l’association d’entreprises, vous devez fournir l’objectId, mais vous pouvez également l’inclure le domain pour mettre à jour la propriété de domain de cette entreprise.
Voici l’ordre de priorité des propriétés d’association des fiches d’informations CRM, le nombre le plus bas étant la priorité la plus élevée :
ChampPrioritéDescription
objectId1L’ID de fiche d’informations CRM (recommandé).
utk2Le jeton d’utilisateur du contact (contacts uniquement).
email3L’adresse e-mail du contact (contacts uniquement).
domain4Le domaine de l’entreprise (entreprises uniquement).

​
Envoi de données supplémentaires

Au-delà de l’envoi de données aux propriétés d’événement et de la mise à jour des propriétés CRM via les occurrences d’événement, vous pouvez inclure des données supplémentaires pour le rendu de la chronologie via l’objet extraData.
L’objet extraData peut seulement contenir un JSON valide. Si le JSON est erroné, l’occurrence sera rejetée et vous recevrez une réponse d’erreur.
Les valeurs des champs extraData sont accessibles selon le type d’événement detailTemplate utilisant la syntaxe {{extraData.fieldName}}. Tous les niveaux d’attribut de extraData sont disponibles par le biais de la notation par points, comme {{extraData.person1.preferredName}}. Par exemple, les modèles ci-dessous utilisent les données de propriété customerName et loginLocation, ainsi que le champ surveyData de extraData envoyé via l’occurrence d’événement. Capture d'écran montrant l'exemple de modèle de rendu ci-dessous sur la chronologie d'un contact. 
{
  "eventTemplateId": "5488733",
  "objectId": "769851",
  "tokens": {
    "customerName": "Tim",
    "loginLocation": "mobileApp",
  },
  "extraData": {
    "surveyData": [
      {
        "question": "How was your login experience?",
        "answer": "Fine!"
      },
      {
        "question": "How likely are you to recommend logging in to a co-worker?",
        "answer": "Extremely likely"
      }
    ]
  }
}