最終更新日: 2025年9月11日
イベント タイプ スキーマを定義し、そのfullyQualifiedNameを取得したら、アプリイベントAPIを使用してイベント オカレンス データを送信できます。イベントデータを送信する際には、事前に作成したスキーマに従う必要があります。スキーマに一致しないリクエストは検証に失敗し、アプリはこのリクエストをキャプチャーしません。

​
イベントオカレンスの送信

1件のイベントオカレンスを送信するには、/integrators/timeline/v4/eventsに対するPOSTリクエストを送信します。リクエスト本文で、イベントタイプの定義済みスキーマの後にイベントデータを含め、eventTypeNameフィールドにfullyQualifiedName値を指定します。
{
  "eventTypeName": "ae000000_integrators-timeline-event-type-id-0000000",
  "objectId": "123456",
  "id": "login-1",
  "properties": {
    "customerName": "Mark S.",
    "loginLocation": "mobileApp"
  }
},

*でマークされたフィールドは必須です。

フィールド型説明
eventTypeName*文字列イベントタイプの完全修飾名。APIを使用してイベントを識別するときに使用します。この値はHubSpotによって自動設定され、イベントタイプの作成後に、APIを使用して取得できます。この値を作成後に変更することはできません。
objectId*文字列イベントオカレンスに関連付けるCRMレコードのID。このフィールドはあらゆるタイプのCRMレコードに使用でき、識別子として推奨されます。CRMレコードの関連付けについて詳細をご確認ください。
email文字列コンタクトの関連付けの場合、関連付けるコンタクトのEメールアドレスを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
utk文字列コンタクトの関連付けの場合、関連付ける既存のコンタクトのユーザートークンを指定できます。CRMレコードの関連付けについて詳細をご確認ください。
domain文字列会社のdomainプロパティー値を設定するときに、objectIdに加えてこのフィールドを含めます。CRMレコードの関連付けについて詳細をご確認ください。
timestamp文字列イベントオカレンスの時刻（ISO 8601形式）を設定します。指定しない場合、既定でイベント オカレンス データの送信時刻のタイムスタンプに設定されます。
propertiesオブジェクトイベントタイプに設定したプロパティーのプロパティー名と値のキーと値のペア。イベントプロパティーの詳細をご確認ください。
extraDataオブジェクトタイムライン表示テンプレートで使用できる追加情報。有効なJSON形式である必要があります。
timelineIFrameオブジェクトこのフィールドが含まれている場合、ユーザーがリンク先のコンテンツをiframeで表示できるハイパーリンクがタイムラインカードに組み込まれます。iframeの使用についての詳細をご確認ください。
id文字列イベントオカレンスの固有ID。イベントタイプ内で重複しないようにする必要があります。指定しない場合、HubSpotによりランダムなUUIDが生成されます。複数のイベントのIDが同一である場合、最初のイベントのIDが受け入れられ、その他は全て拒否されます。

​
CRMレコードの関連付け

各イベントオカレンスは、イベント タイプ スキーマで定義されたCRMオブジェクトタイプを持つCRMレコードに関連付けられている必要があります。アプリイベントAPIには、イベント オカレンス データをCRMレコードに関連付けるための複数のフィールドがあります。サポートされている全てのCRMオブジェクトでは、objectIdフィールドを使用することをお勧めします。ただし、場合によっては他のフィールドを使用することがあります。
  • utk/email：コンタクトのIDが不明な場合は、識別にutkフィールドとemailフィールドのいずれかまたは両方を使用します。両方の識別子を指定すると、コンタクトを作成および更新することもできます。以下に例を示します。
    • utkが既存のコンタクトに一致してもemailが一致しない場合、HubSpotは新しいEメールアドレスで（utkに一致する）コンタクトを更新します。
    • objectIdが指定されていない場合、イベントオカレンスはutk/emailに一致する既存のコンタクトに関連付けられ、一致するコンタクトが見つからない場合はHubSpotによって新しいコンタクトが作成されます。
    • utkのみでは新しいコンタクトレコードを作成できないことにご注意ください。適切な関連付けを確保するために、常にutkとemailを含める必要があります。
  • domain：会社の関連付けの場合、objectIdを指定する必要があります。また、会社のdomainプロパティーを更新するためにdomainを含めることもできます。
以下に、CRMレコードの関連付けプロパティーの優先順位を示します。最も小さい数値が最も高い優先順位となります。
フィールド優先順位説明
objectId1CRMレコードID（推奨）。
utk2コンタクトのユーザートークン（コンタクトのみ）。
email3コンタクトのEメールアドレス（コンタクトのみ）。
domain4会社ドメイン（会社のみ）。

​
追加データの送信

イベントプロパティーへのデータの送信とイベントオカレンスによるCRMプロパティーの更新の他に、extraDataオブジェクトを使用してタイムライン表示のための追加データを含めることができます。
extraDataオブジェクトには有効なJSONのみを含めることができます。JSONの形式が正しくない場合、オカレンスは却下され、エラーレスポンスが返されます。
イベントタイプのdetailTemplateでは、{{extraData.fieldName}}構文を使用してextraDataフィールドの値にアクセスできます。extraDataの全ての属性レベルは、{{extraData.person1.preferredName}}などのドット表記形式で指定できます。 例えば以下のテンプレートでは、customerNameプロパティーとloginLocationプロパティーのデータと、イベントオカレンスにより送信されたextraDataのsurveyDataフィールドが使用されています。 コンタクトタイムラインに表示テンプレートの例がどのように表示されるかを示すスクリーンショット。 
{
  "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"
      }
    ]
  }
}