HubSpotのマーケティング イベント オブジェクトの概要。
crm.objects.marketing_events.read
:マーケティングイベントおよび参加データを取得する権限を付与します。crm.objects.marketing_events.write
:マーケティングイベント情報を作成、削除、変更する権限を付与します。externalEventId
パラメーターとexternalAccountId
パラメーターを必要とするエンドポイントは、イベントを最初に作成した同じアプリでのみ機能します。例えば、アプリAとアプリBという2つの公開アプリを作成し、アプリAに関連付けられた認証とIDを使用してマーケティングイベントを作成した場合、アプリAのみがイベントの読み取り、更新、または新しい参加者の追加を行うことができます。* __ __ __ *同じexternalEventIdとexternalAccountIdを使用して、アプリBで同じイベントにアクセスしようとすると、404エラーが返されます。_ _objectId
を必要とするエンドポイントを使用すると、イベントを最初に作成したアプリに関係なく、上記のセクションに記載されている関連スコープを持つ任意のアプリからイベントにアクセスできます。アプリAがマーケティングイベントを作成した場合、アプリBは引き続きobjectId
ベースのエンドポイントを介して参加者の読み取り、更新、または追加を行うことができます。_ __ _パラメーター | 型 | 説明 |
---|---|---|
eventName | 文字列 | イベントのタイトル。 |
eventType | 文字列 | イベントのタイプ(ウェビナー、展示会など)。 |
eventOrganizer | 文字列 | イベントを主催する個人または組織。 |
eventDescription | 文字列 | イベントの説明。 |
eventUrl | 文字列 | ユーザーが詳細を確認したり、イベントに登録したりできるURL。 |
eventCancelled | ブール値 | イベントがキャンセルされるかどうかを表す値。 |
eventStartTime | 文字列 | イベントの開始時刻を示すISO 8601形式のタイムスタンプ。 |
eventEndTime | 文字列 | イベントの終了時刻を示すISO 8601形式のタイムスタンプ。 |
/marketing/v3/marketing-events/events
にPOST
リクエストを送信して、リクエストの本文にeventName
、externalEventId
、externalAccountId
、eventOrganizer
を指定します。必要に応じて、[上記の表](#イベントプロパティー
)に記載されている追加のプロパティーをリクエストに指定できます。
例えば、アプリのexternalAccountId
が"12345"
で、アプリ内のイベントのexternalEventId
が"67890"
の場合、次のようなリクエストで"Winter webinar"
という名前の新しいイベントを作成できます。
/marketing/v3/marketing-events/events/upsert
エンドポイントにPOST
リクエストを送信することで、マーケティングイベントを更新できます。任意のcustomProperties
、イベントのその他の詳細(イベントの名前、開始時刻、説明など)を含めることができます。
リクエストで指定されたIDを持つマーケティングイベントが既に存在する場合、そのマーケティングイベントが更新されます。存在しない場合は、新しいイベントが作成されます。
例えば、次のリクエストは、「Virtual cooking class」という名前で、IDが4
のイベントを作成します。
/marketing/v3/marketing-events/{objectId}
にPATCH
リクエストを送信して、そのプロパティーを更新できます。
objectId
を取得するには、ナレッジベース記事の手順に従ってHubSpotアカウント上のイベントの詳細を表示し、レコードIDフィールドの下にあるIDを見つけます。_ _イベントが正常に作成されると、レスポンスでobjectId
も返されます。/marketing/v3/marketing-events
エンドポイントにGET
リクエストを送信することもできます。externalEventId
が分かっている場合は、/marketing/v3/marketing-events/{externalEventId}/identifiers
へのGET
リクエストを送信する際に、そのパスとして含めることができます。レスポンスには、全てのマーケティングイベントと各イベントに関連付けられたID(イベントのobjectId
、appInfo
、marketingEventName
、externalAccountId
など)が含まれます。/marketing/v3/marketing-events
にGET
リクエストを送信します。
HubSpot内のレコードで特定のマーケティングイベントの詳細を取得する必要がある場合は、/marketing/v3/marketing-events/{objectId}
へのGET
リクエストでIDをobjectIdとして指定できます。_ _
objectId
を使用して、/marketing/v3/marketing-events/{objectId}
にDELETE
リクエストを送信します。
リクエストが正常に完了すると、204 No Content
レスポンスが返されます。
/marketing-events/v3/marketing-events/batch/update
にPOST
リクエストを送信し、リクエスト本文のinputs配列内で各イベントについて更新するプロパティーを指定します。
例えば、オブジェクトIDが58237132332と54073507364を持つ2つのマーケティングイベントの複数のプロパティーを1つのリクエストで更新する場合、リクエストの本文は次のようになります。
objectId
を使用する場合は、参加状態を記録するコンタクトの コンタクトIDを使用するか、Eメールアドレスを使用できます。
/marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/create
に送信し、リクエスト本文のinputs
配列内のvid
フィールドを使用してコンタクトのIDを指定します。例えば、次のリクエスト本文は、IDが47733471576
のコンタクトの出席データを更新し、joinedAt
とleftAt
プロパティーを介して出席者がイベントに参加および退出した時間を指定する例を示しています。/marketing/v3/marketing-events/{objectId}/attendance/{subscribeState}/email-create
に送信し、リクエスト本文のinputs
配列内のemail
フィールドを使用してコンタクトのEメールを指定します。
inputs
配列にcontactProperties
フィールドを含めることにより、関連付ける任意のプロパティーを新規作成されたコンタクトに設定することができます。それ以外の場合、コンタクトが既に存在する場合は、リクエストで指定されているcontactProperties
は更新されません 。john@example.com
のコンタクトの参加データを更新し、inputs
配列のproperties
オブジェクト内のjoinedAt
フィールドとleftAt
フィールドを使用して、出席者がイベントに参加および退出した時間を指定する例を示しています。objectId
:HubSpotアカウントのマーケティングイベントのレコードID。_ _イベントのobjectIdの使用と外部IDの使用の詳細については、前述のセクションをご確認ください。subscriberState
:コンタクトの新しい参加ステータスと一致する以下の列挙値。REGISTERED
:HubSpotコンタクトがイベントに登録したことを示します。ATTENDED
:HubSpotコンタクトがイベントに出席したことを示します。コンタクトのステータスをATTENDEDに更新する場合は、リクエスト本文のパラメーターとして、ISO 8601インスタント形式で指定したjoinedAt
およびleftAt
タイムスタンプを含めることもできます。CANCELLED
:以前イベントに登録したHubSpotコンタクトが登録をキャンセルしたことを示します。/upsert
または/email-upsert
エンドポイントを使用して出席者のステータスを更新していた場合は、代わりに以下に示す代替エンドポイントを使用できます。ただし、上記のイベント出席エンドポイントと比較すると、これらのエンドポイントを使用しても、次のサポートは提供されません。joinedAt
またはleftAt
プロパティーを指定するexternalEventId
を必要とするエンドポイントを使用する場合は、既存のコンタクトコンタクトIDまたはEメールアドレスのいずれかを使用できます。
externalEventId
として使用し、/marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/create
にPOST
リクエストを送信します。inputs
オブジェクトを指定します。
interactionDateTime
:コンタクトがイベントに登録した日時。vid
:既存のコンタクトのコンタクトID。POST
リクエストを/marketing/v3/marketing-events/attendance/{externalEventId}/{subscriberState}/email-create
に送信します。inputs
オブジェクトを指定します。
interactionDateTime
:コンタクトがイベントに登録した日時。email
:inputs内のemailフィールドの値として指定する、参加者のEメールアドレスexternalEventId
:マーケティングイベントのID。イベントのobjectIdの使用と外部IDの使用の詳細については、 前述のセクションをご覧ください。subscriberState
:コンタクトの新しい参加ステータスと一致する以下の列挙値。
REGISTERED
:HubSpotコンタクトがイベントに登録したことを示します。ATTENDED
:HubSpotコンタクトがイベントに出席したことを示します。コンタクトのステータスをATTENDEDに更新する場合は、リクエスト本文のパラメーターとして、ISO 8601インスタント形式で指定したjoinedAt
およびleftAt
タイムスタンプを含めることもできます。CANCELLED
:以前イベントに登録したHubSpotコンタクトが登録をキャンセルしたことを示します。interactionDateTime
値が変更されていない限り、べき等性があります。これにより、重複したイベントがマーケティング イベント プロパティーにHubSpotによって作成されることなく、参加状態を複数回安全に設定できます。attended
、registered
、cancelled
、noShows
)。contactIdentifier
パスパラメーターとして使用して、GET
リクエストを/marketing/v3/marketing-events/participations/contacts/{contactIdentifier}/breakdown
に送信します。
レスポンスのproperties
フィールドには、コンタクトのイベント参加の概要が含まれています。
externalAccountId
とイベントのexternalEventId
を使用して、GET
リクエストを/marketing/v3/marketing-events/participations/{externalAccountId}/{externalEventId}/breakdown
に送信します。
externalAccountId
とイベントのexternalEventId
を使用して、GET
リクエストを/marketing/v3/marketing-events/participations/{externalAccountId}/{externalEventId}
に送信します。
レスポンスには合計参加数が含まれます。
クエリーパラメーター | 型 | 説明 |
---|---|---|
contactIdentifier | 文字列 | 特定のコンタクトのEメールアドレスまたはID |
state | 列挙 | イベントの参加状態。使用可能な参加状態は、次の通りです。
|
limit | 数値 | 返される結果数の上限を設定します。デフォルトでは、上限は10に設定されています。有効な範囲は1-100です。 |
after | 数値 | レスポンスの結果間のページングに使用されます。レスポンスデータの前のページに指定されたオフセットを調べて、次に返す結果のインデックスを決定します。 |
listId
が必要です。詳細は、HubSpotアカウントのリストの詳細ページで確認できます。
PUT
リクエストを/marketing/v3/marketing-events/associations/{marketingEventId}/lists/{listId}
に送信します。
リクエストが正常に完了すると、204 No content
レスポンスが返されます。
PUT
リクエストを/marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists/{listId}
に送信します。
リクエストが正常に完了すると、204 No content
レスポンスが返されます。
/marketing/v3/marketing-events/associations/{marketingEventId}/lists
にGET
リクエストを送信します。
レスポンスは次のようになります。
GET
リクエストを/marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists
に送信することもできます。
DELETE
リクエストを/marketing/v3/marketing-events/associations/{marketingEventId}/lists/{listId}
に送信します。
リクエストが正常に完了すると、204 No content
レスポンスが返されます。
DELETE
リクエストを/marketing/v3/marketing-events/associations/{externalAccountId}/{externalEventId}/lists/{listId}
に送信します。
リクエストが正常に完了すると、204 No content
レスポンスが返されます。
externalAccountId
:外部アプリの顧客のaccountIdを指定するクエリーパラメーター。appId
:イベントの詳細をリクエストしているHubSpotアプリケーションのIDを指定するクエリーパラメーター。これはアプリのIDになります。externalEventId
:HubSpotが詳細な情報をリクエストしている外部アプリのイベントのIDを指定する、リクエストのURL内のパスパラメーター。eventName
| true | 文字列 | マーケティングイベントの名前。 |
| eventOrganizer
| true | 文字列 | マーケティングイベントの主催者の名前。 |
| eventType
| false | 文字列 | このイベントのタイプを説明します。WEBINAR
、CONFERENCE
、WORKSHOP
| など。 |
| startDateTime
| false | 文字列(date-time) | マーケティングイベントの終了日時。 |
| eventDescription
| false | 文字列 | マーケティングイベントの説明。 |
| eventUrl
| false | 文字列 | 外部イベントアプリケーションでマーケティングイベントが存在するURL。 |
| eventCancelled
| false | ブール値 | マーケティングイベントがキャンセルされたかどうかを示します。デフォルトではfalse
| に設定されます。 |
HubSpotはX-HubSpot-Signature-v3
ヘッダーも送信します。これは、リクエストがHubSpotから送信されたことを確認するために使用できます。署名の詳細とその検証方法については、リクエスト署名を参照してください。
/marketing/v3/marketing-events/{appId}/settings
にPOST
リクエストを送信して、HubSpotにAPIへのURLパスを提供する必要があります。これにより、HubSpotはアプリにリクエストを送信してマーケティングイベントの詳細を取得する方法を決定できます。
POST
リクエストの本文で、eventDetailsURL
フィールドを使用してURLを指定します。eventDetailsURL
は次の2つの要件を満たす必要があります。
%s
文字列を含んでいること。HubSpotはこの文字列をパスパラメーターとして使用し、イベントのID(externalEventId
)に代入します。https://
プレフィックスとドメイン名(例:my.event.app
)を含む、APIリソースへのフルパスであること。https://my.event.app/events/%s
のeventDetailsURL
を設定し、IDが1234-event-XYZ
のイベントの詳細を取得するリクエストを送信する必要がある場合、HubSpotアプリのIDがapp-101
で、アカウントのIDがABC-account-789
だとすると、HubSpotは次のURLにGET
リクエストを送信します。
https://my.event.app/events/1234-event-XYZ?appId=app-101&externalAccountId=ABC-account-789