Última modificación: 11 de septiembre de 2025
Tras definir un esquema de tipo de evento y recuperar su fullyQualifiedName, puedes enviar datos de ocurrencia de eventos a través de la API de eventos de la aplicación. Cuando envíes datos de eventos, tendrás que respetar el esquema que creaste anteriormente. Las solicitudes que no coincidan con el esquema fallarán en la validación y no serán capturadas por la aplicación.

​
Envío de ocurrencias de eventos

Para enviar una ocurrencia de evento única, haz una solicitud de POST a /integrators/timeline/v4/events.En el cuerpo de la solicitud, incluye los datos del evento siguiendo el esquema definido para el tipo de evento junto con el valor fullyQualifiedName en un campo eventTypeName.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Los campos marcados con * son obligatorios.

CampoTipoDescripción
eventTypeName*CadenaEl nombre completo del tipo de evento, que utilizarás para identificarlo a través de la API. Este valor lo establece automáticamente HubSpot y se puede obtener a través de la API después de crear el tipo de evento. Este valor no se puede cambiar después de la creación.
objectId*CadenaEl ID del registro del CRM a asociar con la ocurrencia del evento. Este campo puede utilizarse para todos los tipos de registros de CRM, y es el identificador recomendado. Más información sobre la asociación de registros del CRM.
emailCadenaPara la asociación de contactos, puedes proporcionar la dirección de correo electrónico del contacto a asociar. Más información sobre la asociación de registros del CRM.
utkCadenaPara la asociación de contactos, puedes proporcionar la ficha de usuario de un contacto existente para asociarlo. Más información sobre la asociación de registros del CRM.
domainCadenaIncluye este campo además de objectId para establecer el valor de la propiedad domain de la empresa. Más información sobre la asociación de registros del CRM.
timestampCadenaEstablece la hora de ocurrencia del evento (formatoISO 8601). Si no se proporciona, HubSpot utilizará por defecto la marca de tiempo de cuando se envían los datos de ocurrencia del evento.
propertiesObjetoPares clave-valor de nombres y valores de propiedades que has configurado para el tipo de evento. Más información sobre las propiedades del evento.
extraDataObjetoInformación adicional que estará disponible para las plantillas de representación de la cronología. Debe estar en formato JSON válido.
timelineIFrameObjetoCuando se incluya, la tarjeta de cronología incluirá un hipervínculo que permitirá a los usuarios abrir los contenidos enlazados en un iframe. Más información sobre el uso de iframes.
idCadenaUn identificador único para la ocurrencia del evento. Debe ser único dentro del tipo de evento. Si no se proporciona, HubSpot generará un UUID aleatorio. Cuando varios eventos tengan el mismo ID, se aceptará el primero y se rechazarán todos los demás.

​
Asociación de registros del CRM

Cada suceso debe estar asociado a un registro del CRM, con el tipo de objeto del CRM definido por el esquema de tipo de evento. La API de eventos de la aplicación incluye múltiples campos para asociar los datos de ocurrencia de eventos con los registros del CRM. Para todos los objetos del CRM compatibles, se recomienda utilizar el campo objectId. Sin embargo, hay algunas situaciones en las que puede que quieras utilizar los otros campos.
  • utk/email: si no conoces el ID del contacto, utiliza el campo utk y/o email para identificarlo. Proporcionar estos dos identificadores también te permite crear y actualizar contactos. Por ejemplo:
    • Si utk coincide con un contacto existente pero email no coincide, HubSpot actualizará el contacto (mediante utk) con la nueva dirección de correo electrónico.
    • Si no se proporciona objectId, el evento se asociará a un contacto existente que coincida con utk/email, o HubSpot creará un nuevo contacto si no se encuentra ninguna coincidencia.
    • Ten en cuenta que utk por sí solo no puede crear nuevos contactos. Siempre debes incluir email con utk para garantizar una asociación adecuada.
  • domain: para la asociación de empresas, debes proporcionar la dirección objectId, pero también puedes incluir domain para actualizar la propiedad domain de esa empresa.
A continuación se muestra el orden de prioridad de las propiedades de la asociación de registros del CRM, siendo el número más bajo el de mayor prioridad:
CampoPrioridadDescripción
objectId1El ID del registro del CRM (recomendado).
utk2La ficha de usuario del contacto (solo contactos).
email3La dirección de correo electrónico del contacto (solo contactos).
domain4Dominio de la empresa (solo empresas).

​
Envío de datos adicionales

Además de enviar datos a las propiedades de los eventos y actualizar las propiedades de CRM a través de las ocurrencias de los eventos, puedes incluir datos adicionales para la representación de la cronología a través del objeto extraData.
El objeto extraData solo puede contener JSON válido. Si el JSON está malformado, la ocurrencia será rechazada y recibirás una respuesta de error.
Se puede acceder a los valores del campo extraData del tipo de evento detailTemplate utilizando la sintaxis {{extraData.fieldName}}. Todos los niveles de atributo de extraData están disponibles a través de la notación por puntos, como {{extraData.person1.preferredName}}. Por ejemplo, las plantillas siguientes utilizan los datos de las propiedades customerName y loginLocation, junto con el campo surveyData de extraData enviado a través de la ocurrencia del evento. Captura de pantalla que muestra el aspecto de la plantilla de representación del ejemplo siguiente en la cronología de contactos. 
{
  "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"
      }
    ]
  }
}