最終更新日: 2025年8月22日

Run in Postman

 HubSpotにおける「取引」とは、コンタクトまたは会社との間で進めている商取引を表します。パイプラインステージ上で成約または失注になるまでの間、営業プロセスを通してトラッキングが行われます。取引エンドポイントを使用することにより、取引レコードを作成、管理したり、HubSpotと他のシステムの間で取引データを同期したりできます。 オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、CRMのガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。

​
取引を作成する

新しい取引を作成するには、POSTリクエストを/crm/v3/objects/dealsに送信します。 リクエスト本文のpropertiesオブジェクトに取引データを含めます。また、associationsオブジェクトを追加して、新しい取引を既存のレコード（コンタクト、会社など）またはアクティビティー（ミーティング、メモなど）に関連付けることもできます。

​
プロパティー

取引の詳細は、取引プロパティーに格納されます。HubSpot にはデフォルトの取引プロパティーが用意されていますが、カスタムプロパティーを作成することもできます。 新しい取引を作成する際にはdealnameとdealstageのプロパティーをリクエストに含める必要があります。また、複数のパイプラインがある場合はpipelineも含めます。パイプラインが指定されない場合、デフォルトのパイプラインが使用されます。 利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/dealsに送信して、アカウントの取引プロパティーのリストを取得します。詳しくはプロパティーAPIをご参照ください。

​
注：

APIを介して取引を作成する際は、取引ステージまたはパイプラインの内部IDを使用する必要があります。APIを介して取引を取得すると、内部IDも返されます。取引ステージまたはパイプラインの内部IDは、取引パイプライン設定で確認できます。
例えば、新しい取引レコードを作成する場合、リクエストの内容は以下のようになります。 
{
  "properties": {
    "amount": "1500.00",
    "closedate": "2019-12-07T16:50:06.678Z",
    "dealname": "New deal",
    "pipeline": "default",
    "dealstage": "contractsent",
    "hubspot_owner_id": "910901",
    "hs_all_collaborator_owner_ids": ";12345678;9101112"
  }
}

​
関連付け

また、新しい取引を作成する際には、associationsオブジェクトで既存のレコードまたはアクティビティーに関連付けることもできます。例えば、新しい取引を既存のコンタクトと会社に関連付ける場合、リクエストの内容は以下のようになります。 
{
  "properties": {
    "amount": "1500.00",
    "closedate": "2019-12-07T16:50:06.678Z",
    "dealname": "New deal",
    "pipeline": "default",
    "dealstage": "contractsent",
    "hubspot_owner_id": "910901"
  },
  "associations": [
    {
      "to": {
        "id": 201
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 5
        }
      ]
    },
    {
      "to": {
        "id": 301
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 3
        }
      ]
    }
  ]
}
以下をassociationsオブジェクトに含める必要があります。
パラメーター説明
to取引に関連付けるレコードまたはアクティビティー。一意のid値で指定します。
types取引とレコードまたはアクティビティーの間の関連付けのタイプ。associationCategoryとassociationTypeIdを含めます。デフォルトの関連付けタイプIDはこちらのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。

​
取引を取得する

取引レコードを個別に、または一括で取得できます。
  • 取引を個別に取得するには、GETリクエストを/crm/v3/objects/deals/{dealId}に送信します。
  • 全ての取引のリストを要求するには、GETリクエストを/crm/v3/objects/dealsに送信します。
これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。
パラメーター説明
propertiesレスポンスで返されるプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
propertiesWithHistoryレスポンスで返される現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象の取引レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
associations関連付けられたIDを取得する対象のオブジェクトのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
  • レコードIDまたはカスタム固有IDプロパティーを指定して特定の取引を一括で取得するには、POSTリクエストをcrm/v3/objects/deals/batch/readに送信します。
    • このバッチエンドポイントは関連付けを取得できません。詳しくは、関連付けAPIを使用して関連付けを一括読み取りする方法をご参照ください。
    • 取引IDではなくカスタムの固有IDプロパティーによって取引を取得するには、リクエスト本文にidPropertyパラメーターを含めてプロパティー名を指定します。次に、inputs配列に取引IDではなく固有IDプロパティーの値を含めます。
例えば、取引レコードを一括で取得する場合のリクエストは、以下のいずれかのようになります。 
{
"properties": ["dealname", "dealstage", "pipeline"],
"inputs": [
{
"id": "7891023"
},
{
"id": "987654"
}
]
}
特定のプロパティーの現在の値と過去の値を含む取引を取得するには、以下の通り、リクエスト本文にpropertiesWithHistoryパラメーターを含めます。 
{
  "propertiesWithHistory": [
    "dealstage"
  ],
  "inputs": [
    {
      "id": "7891023"
    },
    {
      "id": "987654"
    }
  ]
}

​
取引を更新する

取引レコードを個別に、または一括で更新できます。既存の取引の場合、APIを介してそのレコードを更新するために使用できるデフォルトの一意の値は、取引IDです。ただし、カスタムの固有IDプロパティーを使用して取引を識別することもできます。
  • レコードIDを基に取引を個別に更新するには、PATCHリクエストに更新対象のデータを含めて/crm/v3/objects/deals/{dealId}に送信します。
  • 複数の取引を更新するには、POSTリクエストを/crm/v3/objects/deals/batch/updateに送信します。リクエストの本文に、取引の識別子と更新するプロパティーを含む配列を含めます。

​
既存の取引を他のレコードまたはアクティビティーに関連付ける

取引を他のCRMレコードやアクティビティーに関連付けるには、PUTリクエストを/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。
associationTypeId値を取得するには、デフォルト値のリストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。
レコード関連付けの詳細については関連付けAPIをご確認ください。

​
関連付けを削除する

取引とレコードまたはアクティビティーの間の関連付けを削除するには、DELETEリクエストを/crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

​
取引レコード上でアクティビティーをピン留めする

リクエストにhs_pinned_engagement_idパラメーターを含めることで、APIを介して取引レコードでアクティビティーをピン留めできます。パラメーターの値には、ピン留めするアクティビティーのIDを指定します。これはエンゲージメントAPIを介して取得できます。レコードごとに1つのアクティビティーをピン留めすることができ、そのアクティビティーはピン留めする前にすでに取引に関連付けられている必要があります。 取引にピン留めするアクティビティーを設定または更新する場合、リクエストは以下のようになります。 
{
  "properties": {
    "hs_pinned_engagement_id": 123456789
  }
}
同じリクエスト内で、取引を作成し、既存のアクティビティーに関連付け、アクティビティーをピン留めすることもできます。以下に例を示します。 
{
  "properties": {
    "dealname": "New deal",
    "pipelines": "default",
    "dealstage": "contractsent",
    "hs_pinned_engagement_id": 123456789
  },
  "associations": [
    {
      "to": {
        "id": 123456789
      },
      "types": [
        {
          "associationCategory": "HUBSPOT_DEFINED",
          "associationTypeId": 213
        }
      ]
    }
  ]
}

​
取引を削除する

取引レコードを個別に、または一括で削除できます。削除した取引レコードは、HubSpot内のごみ箱に追加されます。後からHubSpot内で取引を復元することも可能です。
  • IDを基準に取引を個別に削除するには、DELETEリクエストを/crm/v3/objects/deals/{dealId}に送信します。このリクエストにリクエスト本文は必要ありません。
  • 取引を一括で削除するには、POSTリクエストを/crm/v3/objects/deals/batch/archiveに送信します。以下の例のように、リクエスト本文には取引IDの値をid入力として含めます。
{
  "inputs": [
    {
      "id": "123456"
    },
    {
      "id": "7891011"
    },
    {
      "id": "12123434"
    }
  ]
}
取引の削除について詳しくは、リファレンスドキュメントをご参照ください。