メインコンテンツへスキップ

Run in Postman
以前のバージョンについては、v3の関連付けAPIのドキュメントを参照してください。
関連付けは、HubSpotのCRM上のさまざまなオブジェクトとアクティビティー間の関係を表します。異なるオブジェクトのレコード間（例：コンタクトから会社）でも、同じオブジェクト内（例：会社から会社）でも、レコードを関連付けることができます。関連付けエンドポイントを使用することで、レコード、アクティビティー、またはレコード間の関連付けを作成、取得、更新、削除できます。 関連付けスキーマエンドポイントを使用すると、アカウントでサポートされている関連付けタイプを表示したり、独自の関連付けタイプを作成したり、レコードの関係にラベルを割り当てたりできます。関連付けラベルは、コンタクト、会社、取引、チケット、カスタムオブジェクト間でサポートされており、リストやワークフローなどのHubSpotツール全体で使用できます。 オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、「CRMについて」のガイドをご確認ください。
**注：**v4関連付けAPI は、NodeJS HubSpot Clientのバージョン9.0.0以降でサポートされています。

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

HubSpotには、あらかじめ定義された一連の関連付けタイプが備わっています（例：会社へのコンタクトのラベルなしの関連付け）。しかし、アカウント管理者は独自の関連付けラベルを定義して、レコード関係の追加情報を提供できます（マネージャー、従業員など）。HubSpot定義の関連付けタイプは次の2つです。
  • **プライマリー：**他のレコードが関連付けられるメインの会社。プライマリー関連付けは、リストやワークフローなどのHubSpotツールで使用できます。複数の会社が関連付けられたレコードの場合、このAPIでは、プライマリーと見なされる会社の変更がサポートされます。
  • ラベルなし：コンタクト、会社、取引、チケット、またはカスタムオブジェクトのレコードが関連付けられたときに追加される関連付けタイプ。このタイプは関連付けが存在することを示し、レスポンスでラベルの値が常にnullと返されます。レコードにプライマリー関連付けまたはカスタム関連付けラベルがある場合、これらのタイプは、ラベルなし関連付けタイプの横に表示されます。
HubSpotで定義されている全ての関連付けタイプをこのセクションで参照できます。

​
単一のラベルとペアのラベル

レコード間の関係を表すために使用できる関連付けラベルには、次の2種類があります。
  • **単一：**関係における両方のレコードに適用される1つのラベル。例えば「友人」、「同僚」などです。
  • ペア：1組のラベル。関連付けられたレコードのそれぞれの側の関係性を表すために異なる語が使用される場合です。例えば「親」と「子」、「雇用主**」と「従業員**」などです。ペアのラベルを作成するには、リクエストにinverseLabelフィールドを含めて、ペアの2番目のラベルを指定する必要があります。

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

カスタム関連付けタイプは、HubSpot内で、または関連付けスキーマAPIエンドポイントを使用して作成できます。各オブジェクトペア間に最大で10個の関連付けタイプを作成できます（例：コンタクトと会社、コンタクトとコンタクト）。 APIを使用して関連付けタイプを作成するには、POSTリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信し、リクエストに次の情報を含めます。
  • name：関連付けタイプの内部名。この値にハイフンを含めたり、値の先頭を数字にしたりすることはできません。
  • label：HubSpotで表示される関連付けラベルの名前。
  • inverseLabel（ペアラベルのみ）：ラベルのペアにおける2番目のラベルの名前。
例えば、リクエストは次のようになります。

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

特定のオブジェクト間の関連付けタイプを表示するには、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。 各項目に以下が含まれる配列が返されます。
  • **category：**関連付けタイプがHubSpotとユーザーのどちらによって作成されたか（HUBSPOT_DEFINEDまたはUSER_DEFINED）を示します。
  • **typeId：**その関連付けタイプの数値ID。これを使用して、レコードを関連付けるときにラベルを設定します。HubSpotで定義されている全てのtypeId値については、このリストを参照してください。
  • **label：**英数字のラベル。「ラベルなし」関連付けタイプの場合、これはnullになります。
また、これらの値はHubSpotの関連付け設定にもあります。

​
レコードを関連付ける

​
ラベルなしでレコードを関連付ける

2つのレコード間に既定のラベルなし関連付けを作成したり、レコードにラベルなし関連付けを一括で設定したりできます。2つのレコード間に既定の関連付けを個別に設定するには、PUTリクエストを /crm/v4/objects/{fromObjectType}/{fromObjectId}/associations/default/{toObjectType}/{toObjectId}に送信します。 リクエストURLには、次の情報を含めます。
  • fromObjectType**：**関連付けるオブジェクトのID。ID値を見つけるには、このオブジェクトタイプIDのリストを参照してください。コンタクト、会社、取引、チケット、メモには、オブジェクト名（contact、companyなど）を使用できます。
  • fromObjectId**：**関連付けるレコードのID。
  • toObjectType**：**レコードの関連付け先となるオブジェクトのID。ID値を見つけるには、このオブジェクトタイプIDのリストを参照してください。コンタクト、会社、取引、チケット、メモには、オブジェクト名（contact、companyなど）を使用できます。
  • toObjectId**：**関連付け先となるレコードのID。
例えば、IDが12345であるコンタクトレコードを、IDが67891である会社レコードに関連付ける場合、リクエストURLは/crm/v4/objects/contact/12345/associations/default/company/67891になります。 既定の関連付けを一括で設定するには、POSTリクエストをcrm/v4/associations/{fromObjectType}/{toObjectType}/batch/associate/defaultに送信します。リクエスト本文に、関連付けるレコードのobjectId値を含めます。
**注：**1つのレコードに含めることができる関連付けの数は、オブジェクトとHubSpotの配信登録によって異なります。

​
ラベル付きでレコードを関連付ける

2つのレコードを関連付けて、その関連付けを記述するラベルを設定するには、PUTリクエストを/crm/v4/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}に送信します。リクエスト本文に、作成する関連付けのタイプを示すassociationCategoryとassociationTypeIdを含めます。 ラベルのない関連付けを作成する場合は、上記のセクションで概説した、associationCategoryやassociationTypeIdを必要としない既定のエンドポイントを使用できます。ラベルを使った関連付けを作成する場合は、この既定のタイプIDのリストを参照できます。または、これらのオブジェクト間のカスタム関連付けタイプを取得する必要があります。
**注：**クロスオブジェクトおよびペアになったラベルの関係の場合は、正しい方向を示すtypeIdを必ず使用してください（例：コンタクトから会社、会社からコンタクト、従業員からマネージャー、マネージャーから従業員）。
例えば、カスタムラベルを使用してコンタクトを取引に関連付けるには、次のようにします。 1.GETリクエストを/crm/v4/associations/contact/deal/labelsに送信します。 2.応答の中で、ラベルのtypeId値とcategory値を確認します。IDは数値で（例えば36）、カスタムラベルの場合、カテゴリーは常にUSER_DEFINEDです。 3.次のリクエスト本文を使用して、PUTリクエストを/crm/v4/objects/contact/{objectId}/associations/deal/{toObjectId}に送信します。 
/// Example request body
[
  {
    "associationCategory": "USER_DEFINED",
    "associationTypeId": 36
  }
]

​
関連付けの制限を設定および管理する

オブジェクト間で関連付けられるレコードの数や、ラベルを使って関連付けを記述できる頻度に対して、制限を設定することができます。また、技術的な制限やご利用のHubSpotの配信登録に応じた制限もあります。

​
関連付けの制限を作成または更新する

オブジェクト間の関連付けの制限を新規作成したり、既存の制限を更新したりできます。
  • 制限を作成するには、POSTリクエストをcrm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/createに送信します。
  • 既存の制限を更新するには、POSTリクエストをcrm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/updateに送信します。
リクエスト本文に、以下のものを使用したinputsを含めます。
パラメーター説明
category制限を設定する対象の関連付けのカテゴリー。HUBSPOT_DEFINEDまたはUSER_DEFINEDのいずれかです。
typeId制限を設定する対象となる関連付けタイプの数値ID。既定のtypeId値のリストを参照するか、カスタムラベルの値を取得してください。
maxToObjectIds関連付けタイプで許容される関連付けの最大数。
例えば、1つの取引に関連付けられるコンタクトは最大で5つ、取引の「Point of contact」というラベルを付けられるコンタクトは1つだけ、という制限を設定する場合には、次のようなリクエストになります。 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/create
{
  "inputs": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "maxToObjectIds": 5
    },
    {
      "category": "USER_DEFINED",
      "typeId": 35,
      "maxToObjectIds": 1
    }
  ]
}

​
関連付け制限を取得する

  • 定義されている全ての関連付け制限を読み取るには、GETリクエストを/crm/v4/associations/definitions/configurations/allに送信します。これにより、全てのオブジェクトで定義されているカスタム関連付け制限が返されます。
  • 特定の2つのオブジェクト間の関連付け制限を読み取るには、GETリクエストを/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}に送信します。
どちらのリクエストの場合も、応答では関連付けのcategory、typeId、maxToObjectIds、labelの値が返されます。例えば、取引とコンタクトの間の制限を取得する場合、応答は次のようになります。 
//Example response GET crm/v4/associations/definitions/configurations/deal/contact
{
  "results": [
    {
      "category": "HUBSPOT_DEFINED",
      "typeId": 3,
      "userEnforcedMaxToObjectIds": 5,
      "label": null
    }
  ]
}

​
関連付けの制限を削除する

特定の関連付け制限を削除するには、POSTリクエストを/crm/v4/associations/definitions/configurations/{fromObjectType}/{toObjectType}/batch/purgeに送信します。リクエスト本文に、制限を削除する対象の関連付けタイプのcategory値とtypeId値を含めます。 例えば、取引とコンタクトの間の「Point of contact」制限を削除するには、次のようなリクエストになります。 
//Example request POST crm/v4/associations/definitions/configurations/deal/contact/batch/purge
{
  "inputs": [
    {
      "category": "USER_DEFINED",
      "typeId": 35
    }
  ]
}
これが成功すると204レスポンスが返され、含まれる制限はシステムの既定値に戻ります（つまり多くのコンタクトにPoint ofcontactというラベルを使用できます）。

​
高い関連付け使用率に関するレポート

１つのレコードに可能な関連付けの数には、技術的な制限があります。関連付けAPIを使用すると、関連付けの上限に近づいている、または上限に達したレコードのレポートを取得できます。 レポートを取得するには、POSTリクエストをcrm/v4/associations/usage/high-usage-report/{userID}に送信します。ファイルには、関連付け制限の80%以上を使用しているレコードが含まれます。例えば、1つの会社を最大50,000件のコンタクトに関連付けることができる場合、既に40,000件以上のコンタクトが関連付けられている会社がファイルに含まれます。ファイルは、リクエストURLにIDが含まれていたユーザーのEメールに送信されます。ユーザーAPIを使用してユーザーIDを取得する方法をご確認ください。

​
関連付けタイプID値

HubSpotで定義された、関連付けのタイプを指定するassociationTypeId値を以下の表に示します。関連付けタイプは、含まれるオブジェクトと関連付けの方向によって異なります（例えば「コンタクトから会社」は「会社からコンタクト」とは異なります）。カスタムオブジェクトまたはカスタム関連付けラベルを作成する場合、該当する関連付けタイプには固有のtypeId値があり、これらの値を取得するか、HubSpotの関連付け設定でこれらの値を見つける必要があります。
注：既定の会社関連付けタイプには、ラベルなし関連付けタイプとプライマリー関連付けタイプが含まれています。レコードに複数の会社が関連付けられている場合、1つだけをプライマリー会社にすることができます。その他の関連付けには、ラベルがないか、またはカスタム関連付けラベルを付けることができます。

​
v1関連付け（レガシー）

v1関連付けAPIを使用している場合、レコードを関連付けるときに使用するIDについて、下記の表を参照してください。
関連付けタイプID
コンタクトから会社へ1
会社からコンタクトへ（既定）2
会社からコンタクトへ（全ラベル）280
取引からコンタクトへ3
コンタクトから取引へ4
取引から会社へ5
会社から取引へ6
会社からエンゲージメントへ7
エンゲージメントから会社へ8
コンタクトからエンゲージメントへ9
エンゲージメントからコンタクトへ10
取引からエンゲージメントへ11
エンゲージメントから取引へ12
親会社から子会社へ13
子会社から親会社へ14
コンタクトからチケットへ15
チケットからコンタクトへ16
チケットからエンゲージメントへ17
エンゲージメントからチケットへ18
取引から商品項目へ19
商品項目から取引へ20
会社からチケットへ25
チケットから会社へ26
取引からチケットへ27
チケットから取引へ28
Last modified on December 10, 2025