CRM API | CRMカード - HubSpot docs

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

Run in Postman

公開アプリ内でカスタムCRMカードを作成し、HubSpotのコンタクト、会社、取引、チケットのレコードに他のシステムからの情報を表示できます。各アプリには、最大25枚のCRMカードを含めることができます。

2025年6月16日以降、この記事に記載されている従来のCRMカードの機能はサポートされなくなり、2026年10月31日に正式に廃止されます。この変更の詳細についてはHubSpot開発者変更ログをご確認ください。従来のCRMカードは、プロジェクトでUI拡張機能として作成できるアプリカードとは異なります。新しいアプリカードでは、最新のReactベースのツールセットが使用され、柔軟性、カスタマイズ性、インタラクティブ性が向上しています。現在ご自身のアプリに旧型CRMカードが含まれている場合は、プロジェクトフレームワークに移行して新しいアプリカードを使用する方法をご確認ください。

使用例: アプリマーケットプレイスに掲載する、バグ追跡ソフトウェア用の連携を構築しているとします。サポート担当者がユーザーに対応する際に参照できるよう、コンタクトレコードに追跡対象のバグが表示されるようにしたいと考えています。アプリにカスタムカードを定義すると、この情報をHubSpotコンタクトレコード上に表示できます。

カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカードにそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。例えば、HubSpot内でアプリ独自のUIを表示するためのモーダルを開くアクションをアプリに組み込むことができます。

スコープの要件

カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。例えば、CRMカードをコンタクトレコードに表示するには、アプリにcrm.objects.contacts.readスコープとcrm.objects.contacts.writeスコープが設定されている必要があります。後でアプリからCRMオブジェクトのスコープを削除する必要が生じたら、まず、それらのオブジェクトタイプを対象とした既存のカードを全て削除する必要があります。スコープの詳細およびアプリの認証URLの設定については、OAuthのドキュメントをご参照ください。

CRMカードを作成する

アプリのCRMカードは、APIを介して作成することも、開発者アカウントでのアプリの編集によって作成することもできます。APIを介してカードを設定する方法について詳しくは、リファレンスドキュメントをご確認ください。 HubSpotのUIを使用してCRMカードを作成するには、次の手順に従います。

HubSpot開発者アカウントで、メインナビゲーションにある［アプリ］に移動します**。 **
カードを追加する対象のアプリを選択します。
左のサイドバーメニューで［CRMカード］を選択します**。 **
右上の［CRMカードを作成］をクリックします**。 **

以降のセクションで、各タブでの設定オプションについて詳しく説明します。

開発者プロジェクトを使用して構築されたUI拡張機能では、外部コンテンツをフレーム内に表示するなど、より柔軟な方法でデータを表示してユーザーとやり取りできます。連携で非公開アプリを使用することが可能な場合は、UI拡張機能のクイックスタートガイドでUI拡張機能の導入方法をご確認ください。また、HubSpotのサンプルプロジェクトを参照して、UI拡張機能で実現可能なことの例をご確認いただくこともできます。

データリクエスト

HubSpotユーザーが、CRMカードが設定されているCRMレコードを表示すると、HubSpotが連携にデータ取得リクエストを送信します。HubSpotが指定されたターゲットURLに送信するこのリクエストには、一連の既定のクエリーパラメーターの他に、カードの設定として指定されたプロパティーデータを含むパラメーターが追加されます。

［データ取得］フィールドに、データの取得元となるURLを入力します。_ _APIでは、このURLがtargetUrlフィールドに追加されます。
［ターゲットレコードタイプ］セクションで、スイッチをクリックしてオンに切り替え、カードを表示するCRMレコードを選択します。_ _次に、［HubSpotから送信されたプロパティー］ドロップダウンメニューを使用して、リクエストURLにクエリーパラメーターとして含めるHubSpotプロパティーを選択します**。 **APIでは、各レコードタイプとそれに対応するプロパティーがobjectTypes配列内のオブジェクトとして追加されます。

{
  "title": "New CRM Card",
  "fetch": {
    "targetUrl": "https://www.example.com/demo-fetch",
    "objectTypes": [
      {
        "name": "contacts",
        "propertiesToSend": [
          "firstname",
          "email",
          "lastname"
        ]
      }
    ]
  }
...
}

リクエストの例

上記のように設定すると、HubSpotは次のようにGETリクエストを送信します。

https://www.example.com/demo-fetch?userId=12345&userEmail=loggedinuser@hubspot.com&associatedObjectId=53701&associatedObjectType=CONTACT&portalId=987654&firstname=Tim&email=timrobinson@itysl.com&lastname=Robinson

パラメーター	型	説明
`userId`	デフォルト	CRMレコードを読み込んだHubSpotユーザーのID。
`userEmail`	デフォルト	CRMレコードを読み込んだユーザーのEメールアドレス。
`associatedObjectId`	デフォルト	読み込まれたCRMレコードのID。
`associatedObjectType`	デフォルト	読み込まれたCRMレコードのタイプ（コンタクト、会社、取引など）。
`portalId`	デフォルト	CRMレコードが読み込まれたHubSpotアカウントのID。
`firstname`	カスタム	［HubSpotから送信されたプロパティー］ドロップダウンメニュー（アプリ内）および`propertiesToSend`配列（API）で指定された、コンタクトの名。_ _
`email`	カスタム	［HubSpotから送信されたプロパティー］ドロップメニュー（アプリ内）および`propertiesToSend`配列（API）で指定された、コンタクトのEメールアドレス。_ _
`lastname`	カスタム	［HubSpotから送信されたプロパティー］ドロップダウンメニュー（アプリ内）および`propertiesToSend`配列（API）で指定された、コンタクトの姓。_ _

注：

接続は3秒以内に確立される必要があり、5秒が経過するとリクエストはタイムアウトします。

レスポンスの例

以下に、インテグレーターが上記のリクエストに対して返すレスポンスの例を示します。

{
  "results": [
    {
      "objectId": 245,
      "title": "API-22: APIs working too fast",
      "link": "http://example.com/1",
      "created": "2016-09-15",
      "priority": "HIGH",
      "project": "API",
      "description": "Customer reported that the APIs are just running too fast. This is causing a problem in that they're so happy.",
      "reporter_type": "Account Manager",
      "status": "In Progress",
      "ticket_type": "Bug",
      "updated": "2016-09-28",
      "actions": [
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/edit-iframe-contents",
          "label": "Edit",
          "associatedObjectProperties": []
        },
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/reassign-iframe-contents",
          "label": "Reassign",
          "associatedObjectProperties": []
        },
        {
          "type": "ACTION_HOOK",
          "httpMethod": "PUT",
          "associatedObjectProperties": [],
          "uri": "https://example.com/tickets/245/resolve",
          "label": "Resolve"
        },
        {
          "type": "CONFIRMATION_ACTION_HOOK",
          "confirmationMessage": "Are you sure you want to delete this ticket?",
          "confirmButtonText": "Yes",
          "cancelButtonText": "No",
          "httpMethod": "DELETE",
          "associatedObjectProperties": ["protected_account"],
          "uri": "https://example.com/tickets/245",
          "label": "Delete"
        }
      ]
    },
    {
      "objectId": 988,
      "title": "API-54: Question about bulk APIs",
      "link": "http://example.com/2",
      "created": "2016-08-04",
      "priority": "HIGH",
      "project": "API",
      "reported_by": "ksmith@hubspot.com",
      "description": "Customer is not able to find documentation about our bulk Contacts APIs.",
      "reporter_type": "Support Rep",
      "status": "Resolved",
      "ticket_type": "Bug",
      "updated": "2016-09-23",
      "properties": [
        {
          "label": "Resolved by",
          "dataType": "EMAIL",
          "value": "ijones@hubspot.com"
        },
        {
          "label": "Resolution type",
          "dataType": "STRING",
          "value": "Referred to documentation"
        },
        {
          "label": "Resolution impact",
          "dataType": "CURRENCY",
          "value": "94.34",
          "currencyCode": "GBP"
        }
      ],
      "actions": [
        {
          "type": "IFRAME",
          "width": 890,
          "height": 748,
          "uri": "https://example.com/edit-iframe-contents",
          "label": "Edit"
        },
        {
          "type": "CONFIRMATION_ACTION_HOOK",
          "confirmationMessage": "Are you sure you want to delete this ticket?",
          "confirmButtonText": "Yes",
          "cancelButtonText": "No",
          "httpMethod": "DELETE",
          "associatedObjectProperties": ["protected_account"],
          "uri": "https://example.com/tickets/245",
          "label": "Delete"
        }
      ]
    }
  ],
  "settingsAction": {
    "type": "IFRAME",
    "width": 890,
    "height": 748,
    "uri": "https://example.com/settings-iframe-contents",
    "label": "Settings"
  },
  "primaryAction": {
    "type": "IFRAME",
    "width": 890,
    "height": 748,
    "uri": "https://example.com/create-iframe-contents",
    "label": "Create Ticket"
  }
}

プロパティー	タイプ	説明
`results`	配列	最大5つの有効なカードプロパティーから成る配列。特定のCRMオブジェクトにこれよりも多くのプロパティーが含まれる場合は、アプリからリンクを設定できます。
`objectId`	数値	このオブジェクトの固有ID。
`title`	文字列	このオブジェクトのタイトル。
`link`	文字列	ユーザーがオブジェクトに関する詳細を取得するために使用できるURL。このプロパティーは任意指定ですが、リンクを持つオブジェクトがない場合は、`null`を指定してください。
`created`	文字列	オブジェクトの作成日を示す、カードの設定で定義されたカスタムプロパティー。
`priority`	文字列	外部チケットの優先度レベルを示す、カードの設定で定義されたカスタムプロパティー。
`actions`	配列	ユーザーが実行できるアクションのリスト。
`properties`	プロパティー	カード設定で定義されていないカスタムプロパティーのリスト。このリストを使用して、特定のオブジェクトに固有のプロパティーを表示することができます。これらのプロパティーは、カード設定で定義されたプロパティーの後に指定した順に示されます。
`settingsAction`	オブジェクト	ユーザーがアプリの設定を更新できるようになるiframeアクション。
`primaryAction`	オブジェクト	レコードタイプのプライマリーアクション（通常は作成アクション）。
`secondaryActions`	配列	カードに表示される他のアクションのリスト。

リクエスト署名

リクエストが実際にHubSpotから送信されていることを確認するために、リクエストには次のリクエストヘッダーが組み込まれます。このヘッダーには、アプリケーションのアプリシークレットのハッシュとリクエストの詳細が設定されます。 X-HubSpot-Signature: <some base64 string> この署名を検証するには、次の手順に従います。

<app secret> + <HTTP method> + <URL> + <request body> (if present)の形式で連結した文字列を作成します。
連結した文字列のSHA-256ハッシュを生成します。
ハッシュ値を署名と比較します。一致する場合、リクエストは検証に合格したことになります。一致しない場合は、転送中のリクエストの改ざん、またはエンドポイントに対するリクエストのなりすましが発生した恐れがあります。

HubSpotからのリクエストを検証する方法は、こちらでご確認いただけます。

カードプロパティー

［カードプロパティー］タブで、HubSpotのCRMカード上に表示させるカスタムプロパティーを定義します。_ _定義が完了すると、連携によってこれらのプロパティーがレスポンスに組み込まれ、値が取り込まれます。

［プロパティーを追加］をクリックし、カードに表示する新しいプロパティーを追加します**。 **データ取得呼び出しに対して返すペイロードには、これら全てのプロパティーに値が設定されている必要があります。
右側のパネルで、プロパティーの一意の名前、表示ラベル、データタイプを設定します。データタイプとして［通貨］、［日付］、［日時］、［Eメール］、［リンク］、［数値］、［ステータス］、［文字列］のいずれかを選択できます。____ ____拡張プロパティータイプの使用について詳細をご確認ください。
［追加］をクリックしてプロパティーを保存します**。 **

HubSpotがデータリクエストを送信すると、連携からのレスポンスでは、resultsに含まれる各オブジェクトの他の値に加えてこれらのプロパティーの値も取り込まれます。このタブで設定されたプロパティーの他に、連携によって独自のカスタムプロパティーが追加される場合もあり、これらのプロパティーをカードの設定で定義する必要はありません。例えば、以下のレスポンスに含まれるcreatedおよびpriorityは、どちらも［カードプロパティー］タブで定義されたものですが、properties配列では独自のプロパティー定義と値が送信されます。_ _これらのオブジェクト固有のプロパティーは、オブジェクトごとに定義する必要があります。

{
  "objectId": 988,
  "title": "API-54: Question about bulk APIs",
  "link": "http://example.com/2",
  "created": "2016-08-04",
  "priority": "HIGH",
  "properties": [
    {
      "label": "Resolved by",
      "dataType": "EMAIL",
      "value": "ijones@hubspot.com"
    },
    {
      "label": "Resolution type",
      "dataType": "STRING",
      "value": "Referred to documentation"
    },
    {
      "label": "Resolution impact",
      "dataType": "CURRENCY",
      "value": "94.34",
      "currencyCode": "GBP"
    }
  ],
  "actions": [
   ...
  ]
}

カスタムプロパティーを送信する際には、各プロパティーのdataTypeフィールドをCURRENCY、DATE、DATETIME、EMAIL、LINK``NUMERIC、STATUS``STRINGのいずれかに設定できます。プロパティーのタイプによっては、連携で追加のフィールドが必要になる場合があります。以降のセクションで、プロパティーの各タイプについて詳しく説明します。

通貨プロパティー

CURRENCYプロパティーにはcurrencyCodeを含める必要があり、このコードは有効なISO 4217でなければなりません。これにより、ユーザーには正しい通貨記号と数字の書式が表示されます。

{
  "results": [
    {
      "properties": [
        {
          "label": "Resolution impact",
          "dataType": "CURRENCY",
          "value": "94.34",
          "currencyCode": "GBP"
        }
      ]
    }
  ]
}

日付プロパティー

DATEプロパティーはyyyy-mm-ddの形式でなければなりません。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。タイムスタンプを含める必要がある場合は、代わりにDATETIMEプロパティーを使用します。

{
  "results": [
    {
      "properties": [
        {
          "label": "Date",
          "dataType": "DATE",
          "value": "2023-10-13"
        }
      ]
    }
  ]
}

日時プロパティー

DATETIMEプロパティーは特定の時間を示します。エポック以降のミリ秒数で指定する必要があります。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。

{
  "results": [
    {
      "properties": [
        {
          "label": "Timestamp",
          "dataType": "DATETIME",
          "value": "1697233678777"
        }
      ]
    }
  ]
}

Eメールプロパティー

EMAILプロパティーは、Eメールアドレスを含む値に使用されます。これらのプロパティーはmailtoリンクとして表示されます。

{
  "results": [
    {
      "properties": [
        {
          "label": "Email address",
          "dataType": "EMAIL",
          "value": "hobbes.baron@gmail.com"
        }
      ]
    }
  ]
}

リンクプロパティー

LINKプロパティーはハイパーリンクを表示し、新しいウィンドウで開きます。linkLabelを指定しない場合は、URL自体が表示されます。

{
  "results": [
    {
      "properties": [
        {
          "label": "Link property",
          "dataType": "LINK",
          "value": "https://www.hubspot.com",
          "linkLabel": "Test link"
        }
      ]
    }
  ]
}

数値プロパティー

NUMERICプロパティーは数値を表示します。

{
  "results": [
    {
      "properties": [
        {
          "label": "Number",
          "dataType": "NUMERIC",
          "value": "123.45"
        }
      ]
    }
  ]
}

ステータスプロパティー

STATUSプロパティーは色付きのインジケーターとして表示されます。ステータスプロパティーを定義するには、考えられるステータスを記述するoptionTypeを連携で指定する必要があります。ステータスは以下の通りです：

DEFAULT：灰色
SUCCESS：緑色
WARNING：黄色
DANGER：赤色
INFO：青色

{
  "results": [
    {
      "properties": [
        {
          "label": "Status",
          "dataType": "STATUS",
          "value": "Errors occurring",
          "optionType": "DANGER"
        }
      ]
    }
  ]
}

文字列プロパティー

STRINGプロパティーはテキストを表示します。

{
  "results": [
    {
      "properties": [
        {
          "label": "First name",
          "dataType": "STRING",
          "value": "Tim Robinson"
        }
      ]
    }
  ]
}

カスタムアクション

［カスタムアクション］タブでは、ユーザーがアクションボタンをクリックしたときにリクエストするベースURLを定義できます。_ _CRMカードには、さまざまなアクションに対応する複数のアクションURLを含めることができます。

アクションフックおよび確認フックリクエストには、リクエストを検証するためのX-HubSpot-Signatureヘッダーが含まれます。Iframeアクションリクエストには、リクエスト署名は含まれません。詳細については、リクエスト署名をご確認ください。アクションのuriフィールドでアクションURLにアクセスします。データ取得リクエストと同様に、アクションフックには一連のデフォルトのクエリーパラメーターが組み込まれます。アクションにassociatedObjectPropertiesフィールドを含めると、他のクエリーパラメーターを含めることができます。レスポンスは、アクションのタイプによって異なります。以下で、アクションのタイプについて詳しく説明します。

アクションタイプ

Iframeアクション

IFRAMEアクションは、指定されたURLを指すiframeを含むモーダルを開きます。CRM UIからiframeが開かれるとき、リクエスト署名は送信されません。その理由は、元のデータ取得リクエストでiframe URLが返され、追加のプロキシーリクエストが不要であるためです。

{
  "type": "IFRAME",
  "width": 890,
  "height": 748,
  "uri": "https://example.com/iframe-contents",
  "label": "Edit",
  "associatedObjectProperties": ["some_crm_property"]
}

ユーザーがiframe内のアクションを完了したら、モーダルを閉じて、ユーザーを元のCRMレコードにリダイレクトする必要があります。モーダルを閉じるには、連携でwindow.postMessageを使用して、ユーザーの操作が完了したことをCRMに通知します。次のメッセージを使用できます。

{"action": "DONE"}：ユーザーが正常にアクションを完了しました。
{"action": "CANCEL"}：ユーザーがアクションをキャンセルしました。

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

アクションフックのアクション

ACTION_HOOKアクションは、サーバーサイドのリクエストをインテグレーターに送信します。このアクションでユーザーに表示されるUIは、成功メッセージまたはエラーメッセージのみです。このタイプのアクションは、さらなるユーザー入力を必要としない単純な操作に役立ちます。検証用に、リクエストにX-HubSpot-Signatureヘッダーが含まれます。リクエスト署名の詳細については、こちらをご覧ください。

{
  "type": "ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": ["some_crm_property"]
}

httpMethodをGET、POST、PUT、DELETE、またはPATCHに設定することができます。GETまたはDELETEを使用する場合、associatedObjectProperties値がリクエストURLの末尾にクエリーパラメーターとして追加されます。それ以外の場合、プロパティーはリクエスト本文で送信されます。

window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");

確認アクション

CONFIRMATION_ACTION_HOOKアクションは、ACTION_HOOKアクションと同じように動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログを表示するという点が異なります。検証用に、リクエストにX-HubSpot-Signatureヘッダーが含まれます。リクエスト署名の詳細については、こちらをご覧ください。

{
  "type": "CONFIRMATION_ACTION_HOOK",
  "httpMethod": "POST",
  "uri": "https://example.com/action-hook",
  "label": "Example action",
  "associatedObjectProperties": ["some_crm_property"],
  "confirmationMessage": "Are you sure you want to run example action?",
  "confirmButtonText": "Yes",
  "cancelButtonText": "No"
}

CRMカードを削除する

作成後は、アプリの設定からCRMカードを削除できます。

HubSpot開発者アカウントで、メインナビゲーションにある［アプリ］に移動します**。 **
カードを削除するアプリの名前をクリックします。
左のサイドバーメニューで［CRMカード］を選択します**。 **
カードにカーソルを合わせ［削除］をクリックします**。 **

ダイアログボックスで［このカードを削除］をクリックして削除を確定します**。 **

アナリティクスとイベント

CRM

Run in Postman

​スコープの要件

​CRMカードを作成する

​データリクエスト

​リクエストの例

​注：

​レスポンスの例

​リクエスト署名

​カードプロパティー

​通貨プロパティー

​日付プロパティー

​日時プロパティー

​Eメールプロパティー

​リンクプロパティー

​数値プロパティー

​ステータスプロパティー

​文字列プロパティー

​カスタムアクション

​アクションタイプ

​Iframeアクション

​アクションフックのアクション

​確認アクション

​CRMカードを削除する

スコープの要件

CRMカードを作成する

データリクエスト

リクエストの例

注：

レスポンスの例

リクエスト署名

カードプロパティー

通貨プロパティー

日付プロパティー

日時プロパティー

Eメールプロパティー

リンクプロパティー

数値プロパティー

ステータスプロパティー

文字列プロパティー

カスタムアクション

アクションタイプ

Iframeアクション

アクションフックのアクション

確認アクション

CRMカードを削除する