> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# CRM API | CRMカード
export const postmanIcon = ;
[公開アプリ](/apps/legacy-apps/public-apps/overview)内でカスタムCRMカードを作成し、HubSpotのコンタクト、会社、取引、チケットのレコードに他のシステムからの情報を表示できます。各アプリには、最大25枚のCRMカードを含めることができます。
2025年6月16日以降、この記事に記載されている従来のCRMカードの機能はサポートされなくなり、2026年10月31日に正式に廃止されます。この変更の詳細については[HubSpot開発者変更ログ](https://community.hubspot.com/t5/Developer-Announcements/Deprecating-Support-for-Classic-Legacy-CRM-Cards/m-p/1153039#M1048)をご確認ください。
従来のCRMカードは、[プロジェクトでUI拡張機能として作成](https://developers.hubspot.jp/docs/guides/crm/ui-extensions/create)できるアプリカードとは異なります。新しいアプリカードでは、最新のReactベースのツールセットが使用され、柔軟性、カスタマイズ性、インタラクティブ性が向上しています。現在ご自身のアプリに旧型CRMカードが含まれている場合は、[プロジェクトフレームワークに移行](/apps/developer-platform/build-apps/overview)して新しいアプリカードを使用する方法をご確認ください。
**使用例**: アプリマーケットプレイスに掲載する、バグ追跡ソフトウェア用の連携を構築しているとします。サポート担当者がユーザーに対応する際に参照できるよう、コンタクトレコードに追跡対象のバグが表示されるようにしたいと考えています。アプリにカスタムカードを定義すると、この情報をHubSpotコンタクトレコード上に表示できます。
カードはアプリの機能設定の一部として定義できます。アプリをインストールしたユーザーがターゲットのCRMレコードを表示すると、HubSpotはアプリにリクエストを送信して関連するデータを取得し、レコードページ上のカードにそのデータを表示します。アプリには、この情報に基づいてユーザーが実行できるカスタムアクションを指定することもできます。例えば、HubSpot内でアプリ独自のUIを表示するためのモーダルを開くアクションをアプリに組み込むことができます。
## スコープの要件
カスタムCRMカードを作成するアプリは、カードを表示するCRMレコードの変更に必要なOAuthスコープをリクエストする必要があります。例えば、CRMカードをコンタクトレコードに表示するには、アプリに`crm.objects.contacts.read`スコープと`crm.objects.contacts.write`スコープが設定されている必要があります。後でアプリからCRMオブジェクトのスコープを削除する必要が生じたら、まず、それらのオブジェクトタイプを対象とした既存のカードを全て削除する必要があります。
[スコープの詳細](/apps/legacy-apps/authentication/working-with-oauth)およびアプリの認証URLの設定については、OAuthのドキュメントをご参照ください。
## CRMカードを作成する
アプリのCRMカードは、APIを介して作成することも、開発者アカウントでのアプリの編集によって作成することもできます。APIを介してカードを設定する方法について詳しくは、[リファレンスドキュメント](/api-reference/crm-public-app-crm-cards-v3/guide)をご確認ください。
HubSpotのUIを使用してCRMカードを作成するには、次の手順に従います。
* HubSpot開発者アカウントで、メインナビゲーションにある［アプリ］に移動します\*\*。 \*\*
* カードを追加する対象の**アプリ**を選択します。
* 左のサイドバーメニューで［CRMカード］を選択します\*\*。 \*\*
* 右上の［CRMカードを作成］をクリックします\*\*。 \*\*
以降のセクションで、各タブでの設定オプションについて詳しく説明します。
開発者プロジェクトを使用して構築されたUI拡張機能では、外部コンテンツをフレーム内に表示するなど、より柔軟な方法でデータを表示してユーザーとやり取りできます。連携で非公開アプリを使用することが可能な場合は、[UI拡張機能のクイックスタートガイド](/apps/developer-platform/build-apps/overview)でUI拡張機能の導入方法をご確認ください。また、[HubSpotのサンプルプロジェクトを参照](https://developers.hubspot.jp/docs/guides/crm/ui-extensions/sample-extensions/overview)して、UI拡張機能で実現可能なことの例をご確認いただくこともできます。
## データリクエスト
HubSpotユーザーが、CRMカードが設定されているCRMレコードを表示すると、HubSpotが連携にデータ取得リクエストを送信します。HubSpotが指定されたターゲットURLに送信するこのリクエストには、一連の既定のクエリーパラメーターの他に、カードの設定として指定されたプロパティーデータを含むパラメーターが追加されます。
* ［データ取得］フィールドに、データの取得元となる**URL**を入力します。\_ \_APIでは、このURLが`targetUrl`フィールドに追加されます。
* ［ターゲット レコード タイプ］セクションで、**スイッチ**をクリックしてオンに切り替え、カードを表示するCRMレコードを選択します。\_ \_次に、［HubSpotから送信されたプロパティー］ドロップダウンメニューを使用して、リクエストURLにクエリーパラメーターとして含める**HubSpotプロパティー**を選択します\*\*。 \*\*APIでは、各レコードタイプとそれに対応するプロパティーが`objectTypes`配列内のオブジェクトとして追加されます。
```json theme={null}
{
"title": "New CRM Card",
"fetch": {
"targetUrl": "https://www.example.com/demo-fetch",
"objectTypes": [
{
"name": "contacts",
"propertiesToSend": [
"firstname",
"email",
"lastname"
]
}
]
}
...
}
```
### リクエストの例
上記のように設定すると、HubSpotは次のように`GET`リクエストを送信します。
```shell theme={null}
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秒が経過するとリクエストはタイムアウトします。
### レスポンスの例
以下に、インテグレーターが上記のリクエストに対して返すレスポンスの例を示します。
```json theme={null}
{
"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つの有効な[カードプロパティー](#card-properties)から成る配列。特定のCRMオブジェクトにこれよりも多くのプロパティーが含まれる場合は、アプリからリンクを設定できます。 |
| `objectId` | 数値 | このオブジェクトの固有ID。 |
| `title` | 文字列 | このオブジェクトのタイトル。 |
| `link` | 文字列 | ユーザーがオブジェクトに関する詳細を取得するために使用できるURL。このプロパティーは任意指定ですが、リンクを持つオブジェクトがない場合は、`null`を指定してください。 |
| `created` | 文字列 | オブジェクトの作成日を示す、カードの設定で定義された[カスタムプロパティー](#card-properties)。 |
| `priority` | 文字列 | 外部チケットの優先度レベルを示す、カードの設定で定義された[カスタムプロパティー](#card-properties)。 |
| `actions` | 配列 | ユーザーが実行できる[アクション](#action-types)のリスト。 |
| `properties` | プロパティー | カード設定で定義されていないカスタムプロパティーのリスト。このリストを使用して、特定のオブジェクトに固有のプロパティーを表示することができます。これらのプロパティーは、カード設定で定義されたプロパティーの後に指定した順に示されます。 |
| `settingsAction` | オブジェクト | ユーザーがアプリの設定を更新できるようになるiframeアクション。 |
| `primaryAction` | オブジェクト | レコードタイプのプライマリーアクション（通常は作成アクション）。 |
| `secondaryActions` | 配列 | カードに表示される他のアクションのリスト。 |
### リクエスト署名
リクエストが実際にHubSpotから送信されていることを確認するために、リクエストには次のリクエストヘッダーが組み込まれます。このヘッダーには、アプリケーションのアプリシークレットのハッシュとリクエストの詳細が設定されます。
`X-HubSpot-Signature: `
この署名を検証するには、次の手順に従います。
1. `` + `` + `` + ` (if present)`の形式で連結した文字列を作成します。
2. 連結した文字列のSHA-256ハッシュを生成します。
3. ハッシュ値を署名と比較します。一致する場合、リクエストは検証に合格したことになります。一致しない場合は、転送中のリクエストの改ざん、またはエンドポイントに対するリクエストのなりすましが発生した恐れがあります。
HubSpotからのリクエストを検証する方法は、[こちら](/apps/legacy-apps/authentication/validating-requests)でご確認いただけます。
## カードプロパティー
［カードプロパティー］タブで、HubSpotのCRMカード上に表示させるカスタムプロパティーを定義します。\_ \_定義が完了すると、連携によってこれらのプロパティーがレスポンスに組み込まれ、値が取り込まれます。
* ［プロパティーを追加］をクリックし、カードに表示する新しいプロパティーを追加します\*\*。 \*\*データ取得呼び出しに対して返すペイロードには、これら全てのプロパティーに値が設定されている必要があります。
* 右側のパネルで、プロパティーの一意の名前、表示ラベル、データタイプを設定します。データタイプとして［通貨］、［日付］、［日時］、［Eメール］、［リンク］、［数値］、［ステータス］、［文字列］のいずれかを選択できます。**\_\_\_\_** **\_\_\_\_**[拡張プロパティータイプの使用](/apps/legacy-apps/extensions/overview)について詳細をご確認ください。
* ［追加］をクリックしてプロパティーを保存します\*\*。 \*\*
HubSpotがデータリクエストを送信すると、連携からのレスポンスでは、`results`に含まれる各オブジェクトの他の値に加えてこれらのプロパティーの値も取り込まれます。このタブで設定されたプロパティーの他に、連携によって独自のカスタムプロパティーが追加される場合もあり、これらのプロパティーをカードの設定で定義する必要はありません。
例えば、以下のレスポンスに含まれる`created`および`priority`は、どちらも［カードプロパティー］タブで定義されたものですが、`properties`配列では独自のプロパティー定義と値が送信されます。\_ \_これらのオブジェクト固有のプロパティーは、オブジェクトごとに定義する必要があります。
```json theme={null}
{
"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](https://ja.wikipedia.org/wiki/ISO_4217)でなければなりません。これにより、ユーザーには正しい通貨記号と数字の書式が表示されます。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Resolution impact",
"dataType": "CURRENCY",
"value": "94.34",
"currencyCode": "GBP"
}
]
}
]
}
```
### 日付プロパティー
`DATE`プロパティーは`yyyy-mm-dd`の形式でなければなりません。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。タイムスタンプを含める必要がある場合は、代わりに`DATETIME`プロパティーを使用します。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Date",
"dataType": "DATE",
"value": "2023-10-13"
}
]
}
]
}
```
### 日時プロパティー
`DATETIME`プロパティーは特定の時間を示します。エポック以降のミリ秒数で指定する必要があります。これらのプロパティーは、ユーザーのロケールに適した形式で表示されます。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Timestamp",
"dataType": "DATETIME",
"value": "1697233678777"
}
]
}
]
}
```
### Eメールプロパティー
`EMAIL`プロパティーは、Eメールアドレスを含む値に使用されます。これらのプロパティーはmailtoリンクとして表示されます。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Email address",
"dataType": "EMAIL",
"value": "hobbes.baron@gmail.com"
}
]
}
]
}
```
### リンクプロパティー
`LINK`プロパティーはハイパーリンクを表示し、新しいウィンドウで開きます。`linkLabel`を指定しない場合は、URL自体が表示されます。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Link property",
"dataType": "LINK",
"value": "https://www.hubspot.com",
"linkLabel": "Test link"
}
]
}
]
}
```
### 数値プロパティー
`NUMERIC`プロパティーは数値を表示します。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Number",
"dataType": "NUMERIC",
"value": "123.45"
}
]
}
]
}
```
### ステータスプロパティー
`STATUS`プロパティーは色付きのインジケーターとして表示されます。ステータスプロパティーを定義するには、考えられるステータスを記述する`optionType`を連携で指定する必要があります。ステータスは以下の通りです：
* `DEFAULT`：灰色
* `SUCCESS`：緑色
* `WARNING`：黄色
* `DANGER`：赤色
* `INFO`：青色
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "Status",
"dataType": "STATUS",
"value": "Errors occurring",
"optionType": "DANGER"
}
]
}
]
}
```
### 文字列プロパティー
`STRING`プロパティーはテキストを表示します。
```json theme={null}
{
"results": [
{
"properties": [
{
"label": "First name",
"dataType": "STRING",
"value": "Tim Robinson"
}
]
}
]
}
```
## カスタムアクション
［カスタムアクション］タブでは、ユーザーがアクションボタンをクリックしたときにリクエストするベースURLを定義できます。\_ \_CRMカードには、さまざまなアクションに対応する複数のアクションURLを含めることができます。
アクションフックおよび確認フックリクエストには、リクエストを検証するための`X-HubSpot-Signature`ヘッダーが含まれます。Iframeアクションリクエストには、リクエスト署名は含まれません。詳細については、[リクエスト署名](#request-signatures)をご確認ください。
アクションの`uri`フィールドでアクションURLにアクセスします。[データ取得リクエスト](#data-request)と同様に、アクションフックには一連のデフォルトのクエリーパラメーターが組み込まれます。アクションに`associatedObjectProperties`フィールドを含めると、他のクエリーパラメーターを含めることができます。
レスポンスは、アクションのタイプによって異なります。以下で、アクションのタイプについて詳しく説明します。
### アクションタイプ
#### Iframeアクション
`IFRAME`アクションは、指定されたURLを指すiframeを含むモーダルを開きます。CRM UIからiframeが開かれるとき、リクエスト署名は送信されません。その理由は、元のデータ取得リクエストでiframe URLが返され、追加のプロキシーリクエストが不要であるためです。
```json theme={null}
{
"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"}`：ユーザーがアクションをキャンセルしました。
```json theme={null}
window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");
```
#### アクションフックのアクション
`ACTION_HOOK`アクションは、サーバーサイドのリクエストをインテグレーターに送信します。このアクションでユーザーに表示されるUIは、成功メッセージまたはエラーメッセージのみです。このタイプのアクションは、さらなるユーザー入力を必要としない単純な操作に役立ちます。検証用に、リクエストに`X-HubSpot-Signature`ヘッダーが含まれます。[リクエスト署名](#request-signatures)の詳細については、こちらをご覧ください。
```json theme={null}
{
"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の末尾にクエリーパラメーターとして追加されます。それ以外の場合、プロパティーはリクエスト本文で送信されます。
```json theme={null}
window.parent.postMessage(JSON.stringify({"action": "DONE"}), "*");
```
#### 確認アクション
`CONFIRMATION_ACTION_HOOK`アクションは、`ACTION_HOOK`アクションと同じように動作しますが、サーバーサイドのリクエストを実行する前にユーザーに確認ダイアログを表示するという点が異なります。検証用に、リクエストに`X-HubSpot-Signature`ヘッダーが含まれます。[リクエスト署名](#request-signatures)の詳細については、こちらをご覧ください。
```json theme={null}
{
"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"
}
```
`httpMethod`を`GET`、`POST`、`PUT`、`DELETE`、または`PATCH`に設定することができます。`GET`または`DELETE`を使用する場合、`associatedObjectProperties`値がリクエストURLの末尾にクエリーパラメーターとして追加されます。それ以外の場合、プロパティーはリクエスト本文で送信されます。
## CRMカードを削除する
作成後は、アプリの設定からCRMカードを削除できます。
* HubSpot開発者アカウントで、メインナビゲーションにある［アプリ］に移動します\*\*。 \*\*
* カードを削除するアプリの**名前**をクリックします。
* 左のサイドバーメニューで［CRMカード］を選択します\*\*。 \*\*
* カードにカーソルを合わせ［削除］をクリックします\*\*。 \*\*
* ダイアログボックスで［このカードを削除］をクリックして削除を確定します\*\*。 \*\*