Última modificação: 11 de setembro de 2025
Após definir um esquema de tipo de evento e recuperar seu fullyQualifiedName, você pode enviar dados de ocorrência do evento por meio da API de eventos do aplicativo. Ao enviar dados de eventos, você precisa seguir o esquema já criado. As solicitações que não corresponderem ao esquema não passarão na validação e não serão capturadas pelo aplicativo.

​
Envio de ocorrências de evento

Para enviar uma única ocorrência de evento, faça uma solicitação de POST para /integrators/timeline/v4/events.No corpo da solicitação, inclua dados de evento seguindo o esquema definido do tipo de evento juntamente com o valor fullyQualifiedName em um campo eventTypeName.
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

Campos marcados com * são obrigatórios.

CampoTipoDescrição
eventTypeName*StringO nome totalmente qualificado do tipo de evento, usado para identificar o evento via API. Esse valor é automaticamente definido pelo HubSpot e pode ser obtido através da API depois da criação do tipo de evento. Este valor não pode ser alterado após a criação.
objectId*StringO ID do registro de CRM para associar à ocorrência do evento. Este campo pode ser usado para todos os tipos de registros de CRM e é o identificador recomendado. Saiba mais sobre associação de registro de CRM.
emailStringPara associações de contato, você pode fornecer o endereço de e-mail do contato a ser associado. Saiba mais sobre associação de registro de CRM.
utkStringPara associações de contato, você pode fornecer o token de usuário de um contato existente para associar. Saiba mais sobre associação de registro de CRM.
domainStringInclua este campo além de objectId para definir o valor da propriedade de domain da empresa. Saiba mais sobre associação de registro de CRM.
timestampStringDefine a hora da ocorrência do evento (formato ISO 8601). Se não for fornecida, o HubSpot usará como padrão o carimbo de data/hora do envio de dados de ocorrência de evento.
propertiesObjetoPares chave-valor de nomes de propriedades e valores de propriedades que você configurou para o tipo de evento. Saiba mais sobre propriedades de evento.
extraDataObjetoInformações adicionais disponíveis para modelos de renderização de linhas do tempo. Deve estar em um formato JSON válido.
timelineIFrameObjetoQuando incluído, o cartão de linha do tempo conterá um hiperlink que permite que os usuários abram o conteúdo vinculado em um iframe. Saiba mais sobre como usar iframes.
idStringUm identificador exclusivo para a ocorrência do evento. Deve ser exclusivo dentro do tipo de evento. Se não for fornecido, o HubSpot gerará um UUID aleatório. Quando houver vários eventos com o mesmo ID, o primeiro será aceito e todos os outros serão rejeitados.

​
Associação de registro de CRM

Cada ocorrência de evento deve ser associada a um registro de CRM, com o tipo de objeto de CRM definido pelo esquema de tipo de evento. A API de eventos de aplicativo inclui vários campos para associar dados de ocorrência de evento com registros de CRM. Para todos os objetos de CRM compatíveis, recomendamos usar o campo objectId. No entanto, há algumas situações em que outros campos devem ser usados.
  • utk/email: se você não souber o ID do contato, use o campo utk e/ou email para identificação. Fornecer esses dois identificadores também permite criar e atualizar contatos. Por exemplo:
    • Se utk corresponde a um contato existente, mas email não corresponde, o HubSpot atualizará o contato (por utk) com o novo endereço de e-mail.
    • Se nenhum objectId for fornecido, a ocorrência do evento será associada a um contato existente que corresponda ao utk/email, ou HubSpot criará um contato se nenhuma correspondência for encontrada.
    • Observe que o utk sozinho não pode criar novos contatos. Você deve sempre incluir email com utk para que associação seja adequada.
  • domain: para associações de empresa, você deve fornecer o objectId, mas você também pode incluir domain para atualizar a propriedade de domain daquela empresa.
Veja abaixo a ordem de prioridade das propriedades de associação de registros de CRM, em que o menor número tem a maior prioridade:
CampoPrioridadeDescrição
objectId1O ID do registro de CRM (recomendado).
utk2O token de usuário do contato (somente contatos).
email3O endereço de e-mail do contato (somente contatos).
domain4O domínio de empresas (apenas empresas).

​
Enviar dados adicionais

Além de enviar dados para propriedades do evento e atualização de propriedades de CRM via ocorrências de evento, você pode incluir dados adicionais para renderização de linha do tempo através do objeto extraData.
O objeto extraData só pode conter JSON válido. Se o JSON estiver malformado, a ocorrência será rejeitada e você receberá uma resposta de erro.
Valores de campo extraData podem ser acessados pelo tipo de evento detailTemplate usando a sintaxe {{extraData.fieldName}}. Todos os níveis de atributo de extraData estão disponíveis por meio de notação de ponto, como {{extraData.person1.preferredName}}. Por exemplo, os modelos abaixo usam os dados de propriedade customerName e loginLocation com o campo surveyData de extraData enviado através da ocorrência do evento. Captura de tela que mostra a aparência do modelo de renderização abaixo na linha do tempo de contato. 
{
  "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"
      }
    ]
  }
}