カスタムオブジェクト
Marketing Hub
- Enterprise
Sales Hub
- Enterprise
Service Hub
- Enterprise
CMS Hub
- Enterprise
Operations Hub
- Enterprise
In each HubSpot account, there are the standard CRM objects: contacts, companies, deals, and tickets. To represent and organize your CRM data based on your business needs, you can also create custom objects. You can create a custom object in HubSpot, or use the custom objects API to define custom objects, properties, and associations to other CRM objects.
Below, learn how to create and manage custom objects through the API, and see a walkthrough of creating an example custom object.
To learn more about creating custom objects, check out the following posts on the HubSpot developer blog:
Please note: custom objects are specific to each account, and depending on your subscription, there are limits on the number of custom objects you can create. Learn more about your limits in the HubSpot Products & Services catalog.
次の認証方法のいずれかを使用して、カスタムオブジェクトの作成、読み取り、更新を行うことができます。
Please note: as of November 30, 2022, HubSpot API Keys are being deprecated and are no longer supported. Continued use of HubSpot API Keys is a security risk to your account and data. During this deprecation phase, HubSpot may deactivate your key at any time.
You should instead authenticate using a private app access token or OAuth. Learn more about this change and how to migrate an API key integration to use a private app instead.
カスタムオブジェクトを作成するには、まず、オブジェクトスキーマを定義する必要があります。スキーマには、オブジェクトの名前、プロパティー、および他のCRMオブジェクトとの関連付けを含めます。この記事の上部にある[オブジェクトスキーマ]タブで、スキーマリクエストの詳細を確認できます。以下のサンプルチュートリアルで、リクエストの例を確認することもできます。
カスタム オブジェクト スキーマを作成するには、crm/v3/schemas
に対してPOST
リクエストを行います。リクエスト本文に、オブジェクトスキーマの定義(オブジェクトの名前、プロパティー、関連付け)を含めます。
カスタムオブジェクトに名前を付けるときは、次の点に留意してください。
- オブジェクトを作成した後に、オブジェクトの名前とラベルを変更することはできません。
- 名前には、文字、数字、アンダースコア、ハイフンのみを使用できます。
- 名前は文字で始める必要があります。
- 製品の特定の部分では、長いラベルが切り詰められる場合があります。
オブジェクトのプロパティーと関連付けに必要な定義については、以下の説明をお読みください。
リクエスト本文で定義したプロパティーは、個々のカスタム オブジェクト レコードに情報を格納するために使用されます。
Please note: you can have up to 10 unique value properties for each custom object in your HubSpot account.
定義したプロパティーを使用して、以下のプロパティーベースのフィールドに値を入力します。
- requiredProperties:新しいカスタム オブジェクト レコードを作成するときに必要なプロパティー。
- searchableProperties:HubSpotでの検索に使用するためにインデックス付けされるプロパティー。
- primaryDisplayProperty:個々のカスタム オブジェクト レコードに名前を付けるために使用されるプロパティー。
- secondaryDisplayProperties:primaryDisplayPropertyに属する個々のレコードに表示されるプロパティー。
secondaryDisplayProperties
にリストされる最初のプロパティーは、そのタイプが以下のいずれかの場合、オブジェクト インデックス ページにも4つ目のフィルターとして追加されます。string
number
enumeration
boolean
datetime
- UIから表示プロパティーを削除するには、まず、プロパティーを削除してから再作成する必要があります。
デフォルトでは、スキーマリクエストによってプロパティーを作成する際に、type
プロパティーはstring
に設定され、fieldType
プロパティーはtext
に設定されます。以下の値を使用して、さまざまな型のプロパティーを作成できます。
type |
説明 | 有効なfieldType の値 |
---|---|---|
enumeration |
一連のオプションを表す文字列。各オプションをセミコロンで区切って入力します。 | booleancheckbox 、checkbox 、radio 、select |
date |
特定の年、月、日を表すISO 8601形式の値。 | date |
dateTime |
特定の年、月、日、時刻を表すISO 8601形式の値。HubSpotアプリ上には時刻は表示されません。 | date |
string |
プレーンテキスト文字列。文字数の上限は65,536文字です。 | file 、text 、textarea |
number |
数値。小数の桁数は最大1つまで。 | number |
fieldType |
説明 |
---|---|
booleancheckbox |
ユーザーが「はい」または「いいえ」のいずれかを選択できる入力。フォーム内で使用する場合、1つのチェックボックスとして表示されます。 |
checkbox |
プロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。 |
date |
日付値。日付入力として表示されます。 |
file |
ファイルのフォームへのアップロードが可能。ファイルへのURLリンクとして格納および表示されます。 |
number |
一連の数字。10進数または指数表記として記述。 |
radio |
プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。 |
select |
プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。 |
text |
プレーンテキスト文字列。単行テキスト入力として表示されます。 |
textarea |
プレーンテキスト文字列。複数行テキスト入力として表示されます。 |
関連付け
HubSpotは、カスタムオブジェクトに自動的にEメール、ミーティング、メモ、タスク、コール、コミュニケーションオブジェクトを関連付けます。さらに、カスタムオブジェクトに他の標準的なHubSpotオブジェクトや他のカスタムオブジェクトを関連付けることもできます。
スキーマ作成リクエストによって関連付けを作成する場合は、以下の例に示すように、名前を使用して標準のオブジェクトを識別し、objectTypeId
を使用してカスタムオブジェクトを識別します。
全てのカスタムオブジェクトを取得するには、GET
リクエストを/crm/v3/schemas
に送信します。
特定のカスタムオブジェクトを取得する場合は、次のエンドポイントのいずれかに対してGET
リクエストを送信します。
/crm/v3/schemas/{objectTypeId}
/crm/v3/schemas/p_{object_name}
/crm/v3/schemas/{fullyQualifiedName}
。オブジェクトのスキーマに含まれるfullyQualifiedName
を検索できます。これは、p{portal_id}_{object_name}
から派生したものです。アカウント情報APIを使用して、アカウントのポータルIDを確認できます。
例えば、IDが1234
で、lender
という名前のオブジェクトを持つアカウントの場合、リクエストURLは次のようになります。
https://api.hubapi.com/crm/v3/schemas/2-3465404
https://api.hubapi.com/crm/v3/schemas/p_lender
https://api.hubapi.com/crm/v3/schemas/p1234_lender
オブジェクトのスキーマを更新するには、PATCH
リクエストをhttps://api.hubapi.com/crm/v3/schemas/{objectTypeId}
に送信します。
カスタムオブジェクトの定義の完了後:
- オブジェクトの名前とラベル(単数形と複数形)を変更することはできません。
requiredProperties
、searchableProperties
、primaryDisplayProperty
、secondaryDisplayProperties
は、オブジェクトのスキーマを更新することで変更できます。新しいプロパティーを、必須プロパティー、検索可能プロパティー、または表示プロパティーとして設定するには、スキーマを更新する前にそのプロパティーを作成する必要があります。- カスタム オブジェクト プロパティーは、HubSpotで、またはプロパティーAPIを使用して作成および編集できます。
関連付けを更新する
カスタムオブジェクトに他のオブジェクト関連付けを追加するには、POST
リクエストを/crm/v3/schemas/{objectTypeId}/associations
に送信します。
カスタムオブジェクトには、標準のHubSpotオブジェクト(「コンタクト」「会社」「取引」「チケット」など)または他のカスタムオブジェクトを関連付けることができます。以下の例に示すように、toObjectTypeId
フィールドで、カスタムオブジェクトはそのobjectTypeId
値で識別し、標準のオブジェクトはその名前で識別します。例えば、次のような日付形式が対象です。
カスタムオブジェクトは、そのタイプの全てのオブジェクトインスタンスが削除された後にのみ削除できます。カスタムオブジェクトを削除するには、DELETE
リクエストを/crm/v3/schemas/{objectType}
に送信します。
削除したオブジェクトと同じ名前の新しいカスタムオブジェクトを作成する必要がある場合は、DELETE
リクエストを/crm/v3/schemas/{objectType}?archived=true
に送信して、スキーマのハード(物理)削除を行う必要があります。カスタム オブジェクト タイプの削除は、そのタイプの全てのオブジェクトインスタンス、関連付け、カスタムオブジェクトのプロパティーが削除された後のみしかできません。
以下は、サンプル カスタム オブジェクトの作成方法を説明するチュートリアルです。記載されているリクエストの詳細については、記事の上部にある[オブジェクトスキー]タブを参照してください。
このチュートリアルの内容は次のとおりです。
- カスタム オブジェクト スキーマの作成
- カスタム オブジェクト レコードの作成
- カスタム オブジェクト レコードへのHubSpotコンタクトの関連付け
- カスタムオブジェクトとHubSpotチケットとの間の新しい関連付け定義の作成
- 新しいプロパティー定義の作成
- 新しいプロパティーの追加による、オブジェクトスキーマ(
secondaryDisplayProperties
)の更新
目標:CarSpotという自動車販売店では、在庫をHubSpotに保存するために、カスタムオブジェクトを使用したいと考えています。車両の所有権と購入のトラッキングを行うには、車両にコンタクトレコードを関連付ける必要があります。その過程で、HubSpotチケットとカスタムプロパティーを使用して車両メンテナンスのトラッキングも行います。
オブジェクトスキーマを作成する
CarSpotでは、次の属性をプロパティーとして表すことができるオブジェクトスキーマを作成する必要があります。
- 条件(新車または中古車):enumeration
- 販売店受付日:date
- 製造年:number
- メーカー:string
- モデル:string
- VIN:string(固有の値)
- 色:string
- 走行距離:number
- 価格:number
- メモ:string
また、カスタムオブジェクトと標準のコンタクトオブジェクトの関連付けを定義して、車を潜在的な購入者に結び付けられるようにします。
データモデルが完成したら、オブジェクトスキーマを作成するために、POST
リクエストを/crm/v3/schemas
に送信します。このリクエストの本文は次のように設定します。全て
このAPI呼び出しの応答は次のようになります。全てをコピー
After creating the object schema, CarSpot makes sure to note the new object's {objectTypeId}
field, as they'll use this for fetching and updating the object later. They can also use the {fullyQualifiedName}
value, if they prefer.
カスタム オブジェクト レコードを作成する
カスタムオブジェクトが作成されたら、CarSpotは、在庫にある車両ごとにオブジェクトレコードを作成できます。
最初の車両のオブジェクトレコードを作成するために、次のようにリクエスト本文を設定したPOST
リクエストを/crm/v3/objects/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
レコードが作成された後は、id
値を使用して、車両に既存のコンタクトを関連付けることができます。
If they wanted to later retrieve this record along with specific properties, they could make a GET
request to https://api.hubapi.com/crm/v3/objects/2-3465404/181308?portalId=1234567&properties=year&properties=make&properties=model
カスタム オブジェクト レコードを別のレコードに関連付ける
新しい車両レコードの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
に送信して、新しい関連付けを作成します。
このAPI呼び出しの応答は次のようになります。全てをコピー
When creating a new association between two custom objects, specify the custom objects by their objectTypeId in the toObjectTypeId field. For standard objects, you can identify them by name or use the following values:
- Contact: 0-1
- Company: 0-2
- Deal: 0-3
- Ticket: 0-5
新しいプロパティーを定義する
メンテナンスのトラッキングを進めるにつれて、CarSpotはメンテナンスサービスをパッケージにバンドルする機会に気づきました。個々の車両レコードでこれらのメンテナンスパッケージのトラッキングを行うために、利用可能なパッケージを含む新しいenumeration型プロパティーを作成します。
新しいプロパティーを定義するには、次のようにリクエスト本文を設定したPOST
リクエストを/crm/v3/properties/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
プロパティーが作成されたので、このプロパティーを各車両レコードのサイドバーに表示して、営業担当者や技術者が情報をすぐに利用できるようにしたいと考えています。それには、このプロパティーをsecondaryDisplayProperties
に追加するために、次のようにリクエスト本文を設定したPATCH
リクエストを/crm/v3/schemas/2-3465404
に送信します。
このAPI呼び出しの応答は次のようになります。全てをコピー
これで、技術者が車両に関連付けられたコンタクトレコードを開くと、プロパティーがサイドバーのカスタム オブジェクト カードに表示されるようになります。
HubSpotを使用していくにつれて、CarSpotはHubSpotのAPIを通じて、このカスタムオブジェクトを改善し拡張する方法を見出す可能性が高いでしょう。さらに、カスタム オブジェクト データを使用して動的ページを作成することも考えられます。
貴重なご意見をありがとうございました。