カスタムオブジェクト

APPLICABLE PRODUCTS
  • Marketing Hub
    • Enterprise
  • Sales Hub
    • Enterprise
  • Service Hub
    • Enterprise
  • CMS Hub
    • Enterprise
  • Operations Hub
    • Enterprise

HubSpotアカウントごとに、標準CRMオブジェクトとして、コンタクト、会社、取引、チケットがあります。ビジネスニーズに基づいてCRMデータを表示し、整理するためのカスタムオブジェクトを作成することもできます。HubSpotでカスタムオブジェクトを作成するか、カスタムオブジェクトAPIを使用して、カスタムオブジェクト、プロパティー、他のCRMオブジェクトとの関連付けを定義できます。 

以下で、APIを使用してカスタムオブジェクトを作成し、管理する方法を説明し、サンプル カスタム オブジェクトの作成手順を詳しく見ていきます。

カスタムオブジェクトの作成の詳細については、HubSpot開発者ブログの次の投稿をご覧ください。

注:カスタムオブジェクトは各アカウントに固有であり、ご契約内容によっては、作成できるカスタムオブジェクトの数に制限があります。適用される上限について詳しくは、HubSpot製品・サービスカタログをご覧ください。

認証方法

次の認証方法のいずれかを使用して、カスタムオブジェクトの作成、読み取り、更新を行うことができます。

注:2022年11月30日をもってHubSpot APIキーは廃止され、サポートも終了しています。HubSpot APIキーの使用を続けると、アカウントやデータに対するセキュリティー上のリスクが生じます。なお、HubSpotによってこの廃止段階中にお客さまのキーが無効となった可能性があります。

認証には、代わりに非公開アプリのアクセストークンまたはOAuthを使用する必要があります。この変更の詳細と、非公開アプリを使用するようにAPIキーを移行する方法をご確認ください。

カスタムオブジェクトを作成する

カスタムオブジェクトを作成するには、まず、オブジェクトスキーマを定義する必要があります。スキーマには、オブジェクトの名前、プロパティー、および他のCRMオブジェクトとの関連付けを含めます。スキーマリクエストの詳細については、この記事の上部の[オブジェクトスキーマ]タブでご確認いただけます。以下のサンプルチュートリアルで、リクエストの例を確認することもできます。

カスタム オブジェクト スキーマを作成するには、crm/v3/schemasに対してPOSTリクエストを行います。リクエスト本文に、オブジェクトスキーマの定義(オブジェクトの名前、プロパティー、関連付け)を含めます。

カスタムオブジェクトに名前を付ける際は、次の点に留意してください。

  • オブジェクトを作成した後に、オブジェクトの名前とラベルを変更することはできません。
  • 名前には、文字、数字、アンダースコアのみを使用できます。
  • 名前はアルファベットで始める必要があります。
  • 製品の特定の部分では、長いラベルが切り詰められる場合があります。

オブジェクトのプロパティーと関連付けに必要な定義については、以下の説明をお読みください。 

プロパティー

リクエスト本文で定義したプロパティーは、個々のカスタム オブジェクト レコードに情報を格納するために使用されます。

注:HubSpotアカウントで、1つのカスタムオブジェクトにつき作成できる固有の値のプロパティーは10個までです。

定義したプロパティーを使用して、以下のプロパティーベースのフィールドに値を入力します。

  • requiredProperties:新しいカスタム オブジェクト レコードを作成するときに必要なプロパティー。
  • searchableProperties:HubSpotでの検索に使用するためにインデックス付けされるプロパティー。
  • primaryDisplayProperty:個々のカスタム オブジェクト レコードに名前を付けるために使用されるプロパティー。
  • secondaryDisplayProperties:primaryDisplayPropertyに属する個々のレコードに表示されるプロパティー。
    custom-object-secondary-display-properties0
    • secondaryDisplayPropertiesにリストされる最初のプロパティーは、そのタイプが以下のいずれかの場合、オブジェクト インデックス ページにも4つ目のフィルターとして追加されます。
      • string
      • number
      • enumeration
      • boolean
      • datetime
        custom-object-dashboard-filter0
    • UIから表示プロパティーを削除するには、一度プロパティーを削除してから再作成する必要があります。

デフォルトでは、スキーマリクエストによってプロパティーを作成する際に、typeプロパティーはstringに設定され、fieldTypeプロパティーはtextに設定されます。以下の値を使用して、さまざまなタイプのプロパティーを作成できます。

有効なtypeの値
type 説明 有効なfieldTypeの値
enumeration 一連のオプションを表す文字列。各オプションをセミコロンで区切って入力します。  booleancheckboxcheckboxradioselect
date 特定の年、月、日を表すISO 8601形式の値 date
dateTime 特定の年、月、日、時刻を表すISO 8601形式の値。HubSpotアプリ上には時刻は表示されません。 date
string プレーンテキスト文字列。文字数の上限は65,536文字です。 filetexttextarea
number 数値。小数第1位まで。 number
有効なfieldTypeの値 
fieldType 説明
booleancheckbox ユーザーが「はい」または「いいえ」のいずれかを選択できる入力。フォーム内で使用する場合、1つのチェックボックスとして表示されます。
checkbox プロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。
date 日付値。日付入力として表示されます。
file フォームへのファイルのアップロードが可能。ファイルへのURLリンクとして格納および表示されます。
number 一連の数字。10進数または指数表記として記述。
radio プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。
select プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。
text プレーンテキスト文字列。単行テキスト入力として表示されます。
textarea プレーンテキスト文字列。複数行テキスト入力として表示されます。

関連付け

HubSpotは、カスタムオブジェクトに自動的にEメール、ミーティング、メモ、タスク、コール、コミュニケーションオブジェクトを関連付けます。さらに、カスタムオブジェクトに他の標準的なHubSpotオブジェクトや他のカスタムオブジェクトを関連付けることもできます。

スキーマ作成リクエストによって関連付けを作成する場合は、以下の例に示すように、名前を使用して標準のオブジェクトを識別し、objectTypeIdを使用してカスタムオブジェクトを識別します。

// Example associatedObjects array "associatedObjects": [ "CONTACT", "COMPANY", "TICKET", "DEAL", "2-3453932" ]

既存のカスタムオブジェクトを取得する

全てのカスタムオブジェクトを取得するには、GETリクエストを/crm/v3/schemasに送信します。

特定のカスタムオブジェクトを取得する場合は、次のエンドポイントのいずれかに対してGETリクエストを送信します。

例えば、IDが1234で、lenderという名前のオブジェクトを持つアカウントの場合、リクエストURLは次のようになります。

カスタム オブジェクト レコードを取得する

カスタム オブジェクト レコードを取得することもできます。

  • レコードIDの値を使用して特定のレコードを取得するには、crm/v3/objects/{objectType}/{recordId}に対してGETリクエストを送信します。

このエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。 

Use this table to describe parameters / fields
ParameterDescription
properties

レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象のカスタム オブジェクト レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

propertiesWithHistory

レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のカスタム オブジェクト レコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

associations

関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。

  • 複数のレコードを取得するには、crm/v3/objects/{objectType}/batch/readに対してPOSTリクエストを送信します。このバッチエンドポイントは関連付けを取得できません関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。

リクエストで、レコードID(hs_object_id)またはカスタムの固有の識別子のプロパティー。既定で、リクエストのid値はレコードIDを表すので、レコードIDを使用して取得する場合はidPropertyパラメーターは不要です。カスタムの固有の値のプロパティーを使用する場合は、idPropertyパラメーターを含める必要があります。

例えば、カスタム オブジェクト レコードを一括で取得する場合のリクエストは、次のいずれかのようになります。

///Example request body for record ID { "properties": [ "petname" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }
///Example request body for unique value property { "properties": [ "petname" ], "idProperty": "uniquepropertyexample", "inputs": [ { "id": "abc" }, { "id": "def" } ] }
プロパティーの現在の値と過去の値を含むカスタム オブジェクト レコードを取得する場合のリクエストは、次のようになります。
///Example request body for record ID (current and historical values) { "propertiesWithHistory": [ "pet_owner" ], "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

既存のカスタムオブジェクトを更新する

オブジェクトのスキーマを更新するには、PATCHリクエストをhttps://api.hubapi.com/crm/v3/schemas/{objectTypeId}に送信します。

カスタムオブジェクトを定義した後は、以下の点にご留意ください。

  • オブジェクトの名前とラベル(単数形と複数形)を変更することはできません
  • requiredPropertiessearchablePropertiesprimaryDisplayPropertysecondaryDisplayPropertiesは、オブジェクトのスキーマを更新することで変更できます。新しいプロパティーを、必須プロパティー、検索可能プロパティー、または表示プロパティーとして設定するには、スキーマを更新する前にそのプロパティーを作成する必要があります。
  • カスタム オブジェクト プロパティーは、HubSpotで、またはプロパティーAPIを使用して作成および編集できます。 

関連付けを更新する

カスタムオブジェクトに他のオブジェクト関連付けを追加するには、POSTリクエストを/crm/v3/schemas/{objectTypeId}/associationsに送信します。

カスタムオブジェクトには、標準のHubSpotオブジェクト(「コンタクト「会社「取引「チケット」など)または他のカスタムオブジェクトを関連付けることができます。以下の例に示すように、toObjectTypeIdフィールドで、カスタムオブジェクトはそのobjectTypeId値で識別し、標準のオブジェクトはその名前で識別します。

// Example association request body { "fromObjectTypeId": "2-3444025", "toObjectTypeId": "ticket", "name": "cat_to_ticket" }

カスタムオブジェクトを削除する

カスタムオブジェクトは、そのタイプの全てのオブジェクトインスタンスが削除された後にのみ削除できます。カスタムオブジェクトを削除するには、DELETEリクエストを/crm/v3/schemas/{objectType}に送信します。

削除したオブジェクトと同じ名前の新しいカスタムオブジェクトを作成する必要がある場合は、DELETEリクエストを/crm/v3/schemas/{objectType}?archived=trueに送信して、スキーマのハード(物理)削除を行う必要があります。カスタム オブジェクト タイプの削除は、そのタイプの全てのオブジェクトインスタンス、関連付け、カスタムオブジェクトのプロパティーが削除された後のみしかできません。

サンプル カスタム オブジェクト

以下は、サンプル カスタム オブジェクトの作成方法を説明するチュートリアルです。記載されているリクエストの詳細については、記事の上部にある[オブジェクト]タブを参照してください。

このチュートリアルの内容は次のとおりです。

  1. カスタム オブジェクト スキーマの作成
  2. カスタム オブジェクト レコードの作成
  3. カスタム オブジェクト レコードへのHubSpotコンタクトの関連付け
  4. カスタムオブジェクトとHubSpotチケットとの間の新しい関連付け定義の作成
  5. 新しいプロパティー定義の作成 
  6. 新しいプロパティーの追加による、オブジェクトスキーマ( secondaryDisplayProperties)の更新

目標:CarSpotという自動車販売店では、在庫情報をHubSpotに保存するために、カスタムオブジェクトを使用したいと考えています。車両の所有権と購入のトラッキングを行うには、車両にコンタクトレコードを関連付ける必要があります。その過程で、HubSpotチケットとカスタムプロパティーを使用して車両メンテナンスのトラッキングも行います。

オブジェクトスキーマを作成する

CarSpotでは、次の属性をプロパティーとして表すことができるオブジェクトスキーマを作成する必要があります。 

  1. 条件(新車または中古車):enumeration
  2. 販売店受付日:date
  3. 製造年:number
  4. メーカー:string
  5. モデル:string
  6. VIN:string(固有の値)
  7. 色:string
  8. 走行距離:number
  9. 価格:number
  10. メモ:string

また、オブジェクトの使用方法に関するコンテキストを提供する説明を追加し、カスタムオブジェクトと標準のコンタクトオブジェクトの関連付けを定義して、車を潜在的な購入者に結び付けられるようにします。 

データモデルが完成したら、オブジェクトスキーマを作成するために、POSTリクエストを/crm/v3/schemasに送信します。このリクエストの本文は次のように設定します。全て

// Example POST request to https://api.hubspot.com/crm/v3/schemas { "name": "cars", "description": "Cars keeps track of cars currently or previously held in our inventory.", "labels": { "singular": "Car", "plural": "Cars" }, "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "make" ], "searchableProperties": [ "year", "make", "vin", "model" ], "requiredProperties": [ "year", "make", "vin", "model" ], "properties": [ { "name": "condition", "label": "Condition", "type": "enumeration", "fieldType": "select", "options": [ { "label": "New", "value": "new" }, { "label": "Used", "value": "used" } ] }, { "name": "date_received", "label": "Date received", "type": "date", "fieldType": "date" }, { "name": "year", "label": "Year", "type": "number", "fieldType": "number" }, { "name": "make", "label": "Make", "type": "string", "fieldType": "text" }, { "name": "model", "label": "Model", "type": "string", "fieldType": "text" }, { "name": "vin", "label": "VIN", "type": "string", "hasUniqueValue": true, "fieldType": "text" }, { "name": "color", "label": "Color", "type": "string", "fieldType": "text" }, { "name": "mileage", "label": "Mileage", "type": "number", "fieldType": "number" }, { "name": "price", "label": "Price", "type": "number", "fieldType": "number" }, { "name": "notes", "label": "Notes", "type": "string", "fieldType": "text" } ], "associatedObjects": [ "CONTACT" ] }

オブジェクトスキーマを作成した後、CarSpotは新しいオブジェクトの{objectTypeId}フィールドの値を確認します。後でオブジェクトを取得および更新する際にこの値を使用するためです。必要に応じて、{fullyQualifiedName}の値を使用することもできます。

カスタム オブジェクト レコードを作成する

カスタムオブジェクトが作成されたら、CarSpotは、在庫にある車両ごとにオブジェクトレコードを作成できます。

最初の車両のオブジェクトレコードを作成するために、次のようにリクエスト本文を設定したPOSTリクエストを/crm/v3/objects/2-3465404に送信します。

// Example POST request to https://api.hubspot.com/crm/v3/objects/2-3465404 { "properties": { "condition": "used", "date_received": "1582416000000", "year": "2014", "make": "Nissan", "model": "Frontier", "vin": "4Y1SL65848Z411439", "color": "White", "mileage": "80000", "price": "12000", "notes": "Excellent condition. No accidents." } }

このAPI呼び出しの応答は次のようになります。全てをコピー

// Example response body { "id": "181308", "properties": { "color": "White", "condition": "used", "make": "Nissan", "mileage": "80000", "model": "Frontier", "vin": "4Y1SL65848Z411439", "notes": "Excellent condition. No accidents.", "price": "12000", "year": "2014", "date_received": "1582416000000" }, "createdAt": "2020-02-23T01:44:11.035Z", "updatedAt": "2020-02-23T01:44:11.035Z", "archived": false }

レコードが作成された後は、id値を使用して、車両に既存のコンタクトを関連付けることができます。

後から、このレコードと特定のプロパティーを取得する場合は、https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=modelに対してGETリクエストを送信します。

カスタム オブジェクト レコードを別のレコードに関連付ける

新しい車両レコードのID(181308)と別のレコードのIDを使用して、カスタム オブジェクト レコードを別のオブジェクトのレコードに関連付けることができます。

関連付けを作成するには、PUTリクエストを/crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}に送信します。オブジェクトの関係がすでに定義されている場合、associationType値を判別するには、GETリクエストをcrm/v3/schemas/{objectType}に送信します。

例えば、コンタクトID 51と関連付けタイプ75を使用して、CarSpotは車両レコードにコンタクトを関連付けることができます。上記のIDを使用して、次のリクエストURLが作成されます。

https://api.hubspot.com/crm/v3/objects/2-3465404/181308/associations/contacts/51/75

新しい関連付けを定義する

CarSpotは次に、車両の販売後サービスのトラッキングを開始したいと考えています。そのために、HubSpotのチケットを使用して、実施されたメンテナンスをログに記録します。

車両とチケットを関連付けられるようにするために、次のようにリクエストの本文を設定したPOSTリクエストを/crm/v3/schemas/2-3465404/associationsに送信して、新しい関連付けを作成します。

// Example POST request to https://api.hubspot.com/crm/v3/schemas/2-3465494/associations { "fromObjectTypeId": "2-3465404", "toObjectTypeId": "ticket", "name": "car_to_ticket" }

このAPI呼び出しの応答は次のようになります。全てをコピー

// Example response { "id": "121", "createdAt": "2020-02-23T01:52:12.893826Z", "updatedAt": "2020-02-23T01:52:12.893826Z", "fromObjectTypeId": "2-3465404", "toObjectTypeId": "0-5", "name": "car_to_ticket" }

2つのカスタムオブジェクト間に新しい関連付けを作成する場合は、「toObjectTypeId」フィールドで「objectTypeId」を指定して、カスタムオブジェクトを指定します。標準オブジェクトの場合、名前で指定するか、次の値を使用できます。 

  • コンタクト:0-1
  • 会社名:0-2
  • 取引:0-3
  • チケット:0-5

新しいプロパティーを定義する

メンテナンスのトラッキングを進めるにつれて、CarSpotはメンテナンスサービスをパッケージにして提供できる可能性があることに気づきました。個々の車両レコードでこれらのメンテナンスパッケージのトラッキングを行うために、利用可能なパッケージを含む新しいenumeration型プロパティーを作成します。

新しいプロパティーを定義するには、次のようにリクエスト本文を設定したPOSTリクエストを/crm/v3/properties/2-3465404に送信します。

// Example POST request to https://api.hubspot.com/crm/v3/properties/2-3465404 { "groupName": "car_information", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "options": [ { "label": "Basic", "value": "basic" }, { "label": "Oil change only", "value": "oil_change_only" }, { "label": "Scheduled", "value": "scheduled" } ] }

このAPI呼び出しの応答は次のようになります。全てをコピー

// Example response { "updatedAt": "2020-02-23T02:08:20.055Z", "createdAt": "2020-02-23T02:08:20.055Z", "name": "maintenance_package", "label": "Maintenance Package", "type": "enumeration", "fieldType": "select", "groupName": "car_information", "options": [ { "label": "Basic", "value": "basic", "displayOrder": -1, "hidden": false }, { "label": "Oil change only", "value": "oil_change_only", "displayOrder": -1, "hidden": false }, { "label": "Scheduled", "value": "scheduled", "displayOrder": -1, "hidden": false } ], "displayOrder": -1, "calculated": false, "externalOptions": false, "archived": false, "hasUniqueValue": false, "hidden": false, "modificationMetadata": { "archivable": true, "readOnlyDefinition": false, "readOnlyValue": false }, "formField": false }

プロパティーが作成されたので、このプロパティーを各車両レコードのサイドバーに表示して、営業担当者や技術者が情報をすぐに利用できるようにしたいと考えています。それには、このプロパティーをsecondaryDisplayPropertiesに追加するために、次のようにリクエスト本文を設定したPATCHリクエストを/crm/v3/schemas/2-3465404に送信します。 

// Example PATCH request to https://api.hubspot.com/crm/v3/schemas/2-3465404 { "secondaryDisplayProperties": [ "maintenance_package" ] }

このAPI呼び出しの応答は次のようになります。全てをコピー

// Example response { "id": "3465404", "createdAt": "2020-02-23T01:24:54.537Z", "updatedAt": "2020-02-23T02:12:24.175874Z", "labels": { "singular": "Car", "plural": "Cars" }, "requiredProperties": [ "year", "model", "vin", "make" ], "searchableProperties": [ "year", "model", "vin", "make" ], "primaryDisplayProperty": "model", "secondaryDisplayProperties": [ "maintenance_package" ], "portalId": 1234567, "name": "car" }

このようにして、技術者が車両に関連付けられたコンタクトレコードを開くと、プロパティーがサイドバーのカスタム オブジェクト カードに表示されるようになります。

Screen Shot 2020-03-06 at 11.08.41 AM

HubSpotを使用していくにつれて、CarSpotはHubSpotのAPIを通じて、このカスタムオブジェクトを改善し拡張する方法を見出していくことでしょう。さらに、カスタム オブジェクト データを使用して動的ページを作成することも考えられます。


参考になりましたか?
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。