CRM | カスタムオブジェクト

サポートされる製品

次のいずれかの製品またはそれ以上が必要です。

Marketing HubEnterprise

Sales HubEnterprise

Service HubEnterprise

Content HubEnterprise

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

Run in Postman

HubSpotアカウントごとに、標準CRMオブジェクトとして、コンタクト、会社、取引、チケットがあります。ビジネスニーズに基づいてCRMデータを表示し、整理するためのカスタムオブジェクトを作成することもできます。HubSpotでカスタムオブジェクトを作成するか、カスタムオブジェクトAPIを使用して、カスタムオブジェクト、プロパティー、他のCRMオブジェクトとの関連付けを定義できます。このページでは、APIを使用してカスタムオブジェクトを作成、管理する方法を説明し、例を交えてカスタムオブジェクトの作成手順を解説します。カスタムオブジェクトの作成の詳細については、HubSpot開発者ブログの以下の投稿をご参照ください。

注：

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

認証方法

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

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

カスタムオブジェクトを作成するには、まず、オブジェクトスキーマを定義する必要があります。スキーマには、オブジェクトの名前、プロパティー、および他のCRMオブジェクトとの関連付けを含めます。スキーマリクエストの詳細については、この記事の上部の「オブジェクトスキーマ」セクションでご確認いただけます。また、サンプルに関する手順を追った説明でリクエストの例を確認することもできます。カスタムオブジェクトのスキーマを作成するには、crm/v3/schemasに対してPOSTリクエストを送信します。リクエスト本文に、オブジェクトスキーマの定義（オブジェクトの名前、プロパティー、関連付け）を含めます。カスタムオブジェクトに名前を付ける際は、次の点に留意してください。

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

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

プロパティー

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

注：

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

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

requiredProperties: 新しいカスタムオブジェクトレコードを作成するときに必要なプロパティー。
searchableProperties: HubSpotでの検索に使用するためにインデックス付けされるプロパティー。
primaryDisplayProperty: 個々のカスタムオブジェクトレコードに名前を付けるために使用されるプロパティー。
secondaryDisplayProperties: primaryDisplayPropertyに属する個々のレコードに表示されるプロパティー。

custom-object-secondary-display-properties0

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`	プレーンテキスト文字列。単行テキスト入力として表示されます。

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

全てのカスタムオブジェクトを取得するには、/crm/v3/schemasに対してGETリクエストを送信します。特定のカスタムオブジェクトを取得する場合は、次のエンドポイントのいずれかに対して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_lende

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

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

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

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

パラメーター	説明
`properties`	レスポンスで返されるプロパティーのカンマ区切りリスト。リクエスト対象のカスタムオブジェクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
`propertiesWithHistory`	レスポンスで返される現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のカスタムオブジェクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。
`associations`	関連付けられたIDを取得する対象のオブジェクトのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。

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

リクエストで、レコードID（hs_object_id）またはカスタムの固有のIDプロパティーを取得できます。デフォルトで、リクエストのid値はレコードIDを参照するため、レコードIDを使って取得するときにはidPropertyパラメーターは不要です。カスタムの固有の値のプロパティーを使用する場合は、idPropertyパラメーターを含める必要があります。例えば、カスタムオブジェクトレコードを一括で取得する場合のリクエストは、次のいずれかのようになります。

{
  "properties": ["petname"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

{
  "properties": ["petname"],
  "idProperty": "uniquepropertyexample",
  "inputs": [
    {
      "id": "abc"
    },
    {
      "id": "def"
    }
  ]
}

プロパティーの現在の値と過去の値を含むカスタムオブジェクトレコードを取得する場合のリクエストは、次のようになります。

{
  "propertiesWithHistory": ["pet_owner"],
  "inputs": [
    {
      "id": "12345"
    },
    {
      "id": "67891"
    }
  ]
}

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

オブジェクトのスキーマを更新するには、https://api.hubapi.com/crm/v3/schemas/{objectTypeId}に対してPATCHリクエストを送信します。カスタムオブジェクトを定義した後は、以下の点にご留意ください。

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

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

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

カスタムオブジェクトの例

以下で、カスタムオブジェクトのサンプルの作成手順を詳しく見ていきます。記載されているリクエストの詳細については、記事の上部にある「オブジェクト」セクションをご参照ください。ここでは以下の手順について取り上げます。

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

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

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

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

条件（新車または中古車）: enumeration
販売店受付日: date
製造年: number
メーカー: string
モデル: string
VIN: string（固有の値）
色: string
走行距離: number
価格: number
メモ: string

また、オブジェクトの使用方法に関するコンテキストを提供する説明を追加し、カスタムオブジェクトと標準のコンタクトオブジェクトの関連付けを定義して、車を見込み客に結び付けられるようにします。データモデルが完成したら、オブジェクトスキーマを作成するために、/crm/v3/schemasに対してPOSTリクエストを送信します。このリクエストの本文は次のように設定します。

{
  "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に対して送信します。

{
  "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呼び出しの応答は次のようになります。

{
  "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を使用して、カスタムオブジェクトレコードを別のオブジェクトのレコードに関連付けることができます。関連付けを作成するには、/crm/v3/objects/{objectType}/{objectId}/associations/{toObjectType}/{toObjectId}/{associationType}に対してPUTリクエストを送信します。オブジェクトの関係がすでに定義されている場合、associationType値を判別するには、crm/v3/schemas/{objectType}に対してGETリクエストを送信します。例えば、コンタクトID51と関連付けタイプ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**に対して送信して、新しい関連付けを作成します。

{
  "fromObjectTypeId": "2-3465404",
  "toObjectTypeId": "ticket",
  "name": "car_to_ticket"
}

このAPI呼び出しの応答は次のようになります。

{
  "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に送信します。このリクエストの本文は次のようになります。

{
  "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呼び出しの応答は次のようになります。

{
  "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
}

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

{
  "secondaryDisplayProperties": ["maintenance_package"]
}

このAPI呼び出しの応答は次のようになります。

{
  "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"
}

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

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

アポイントメント

関連付けv3

関連付けv3スキーマ

関連付けv4

関連付けv4スキーマ

カート

コマース決済機能

コマースサブスクリプション

会社

コンタクト

コース

カスタムオブジェクト

取引

値引き

エクスポート

料金

目標

インポート

請求書

リード

商品項目

リスト

掲載情報

オブジェクト

注文

担当者／所有者

パートナークライアント

パートナーサービス

パイプライン

製品

プロパティー

プロパティー検証

見積もり

サービス

税

チケット

コミュニケーション

取引分割

フィードバック送信

上限の追跡

オブジェクトライブラリー

スキーマ

Run in Postman

​注：

​認証方法

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

​プロパティー

​注：

​関連付け

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

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

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

​関連付けを更新する

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

​カスタムオブジェクトの例

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

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

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

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

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

注：

認証方法

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

プロパティー

注：

関連付け

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

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

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

関連付けを更新する

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

カスタムオブジェクトの例

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

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

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

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

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