関連付けv4

関連付けは、HubSpotのCRM上のさまざまなオブジェクトとアクティビティー間の関係を表します。関連付けエンドポイントを使用することで、レコード、アクティビティー、またはレコード間の関連付けを作成、取得、更新、削除できます。

関連付けスキーマエンドポイントを使用すると、アカウントでサポートされている関連付けタイプを表示したり、独自の関連付けタイプを作成したり、レコードの関係にラベルを割り当てたりできます。関連付けラベルは、コンタクト、会社、取引、チケット、カスタムオブジェクト間でサポートされており、リストやワークフローなどのHubSpotツール全体で使用できます。

オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、CRMについてのページをご確認ください。

HubSpotで定義されている関連付けタイプ

HubSpotには、あらかじめ定義された一連の関連付けタイプが備わっています（例：会社へのコンタクトのラベルなしの関連付け）。しかし、アカウント管理者は独自の関連付けラベルを定義して、レコード関係の追加情報を提供できます（マネージャー、従業員など）。HubSpot定義の関連付けタイプは次の2つです。 

• プライマリー：他のレコードが関連付けられるメインの会社。プライマリー関連付けは、リストやワークフローなどのHubSpotツールで使用できます。複数の会社が関連付けられたレコードの場合、このAPIでは、プライマリーと見なされる会社の変更がサポートされます。
• ラベルなし：コンタクト、会社、取引、チケット、またはカスタムオブジェクトのレコードが関連付けられたときに追加される関連付けタイプ。このタイプでは関連付けが存在することが示され、レスポンスでラベルの値が必ずnullで返されます。レコードにプライマリー関連付けまたはカスタム関連付けラベルがある場合、これらのタイプは、ラベルなし関連付けタイプの横に表示されます。

関連付けタイプを作成する

カスタム関連付けタイプは、HubSpot内で、または関連付けスキーマAPIエンドポイントを使用して作成できます。

関連付けタイプをAPIを使用して作成するには、POSTリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。

このリクエストの詳細については、この記事の上部にある［関連付けスキーマのエンドポイント］タブを参照してください。

関連付けタイプを取得する

特定のオブジェクト間の関連付けタイプを表示するには、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。

各項目に以下が含まれる配列が返されます。

• category：関連付けタイプがHubSpotとユーザーのいずれによって作成されたかを示します（HUBSPOT_DEFINEDまたはUSER_DEFINED）。
• typeId：関連付けタイプの数値ID。
• label：英数字ラベル。ラベルなし関連付けタイプの場合、nullになります。

レコードを関連付ける

2つのレコード間に既定のラベルなし関連付けを作成したり、レコードにラベルなし関連付けを一括で設定したりできます。

2つのレコード間に既定の関連付けを個別に設定するには、PUTリクエストを/crm/v4 /objects /{fromObjectType} /{fromObjectId} /associations /default /{toObjectType} /{toObjectId}に送信します。

リクエストURLには、次の情報を含めます。

• objectType：関連付けるオブジェクトのタイプ（例：コンタクト）。
• objectId：関連付けるレコードのID。
• toObjectType：レコードを関連付ける先のオブジェクトのタイプ（例：会社）。 
• toObjectId：関連付け先のレコードのID。

既定の関連付けを一括で設定する場合、POSTリクエストをcrm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/defaultに送信します。リクエスト本文には、関連付けるレコードのobjectId値を含めます。

レコードを関連付けて関連付けラベルを設定する

2つのレコードを関連付けて、その関連付けについて説明するラベルを設定するには、PUTリクエストを/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}に送信します。

リクエスト本文に、作成する関連付けタイプを示すcategoryとtypeIdを含めます。以下に例を示します。

制限

• オブジェクトタイプ（コンタクトや会社など）間で最大10個の関連付けラベルを作成できます。
• 1つのレコードに含めることができる関連付けの数は、オブジェクトとHubSpotサブスクリプションによって異なります。
• /crm/v4/associations/{fromObjectType}/{toObjectType}/batch/readエンドポイントに一括読み取りリクエストを送信する場合：
  
  • 入力できるIDの最大数は11,000件です。
  • レスポンスの各ページで返される関連付けの既定数は1,000件です。