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

Run in Postman

 プロパティーは、CRMレコードに情報を格納するために使用します。HubSpotでは、CRMオブジェクトごとにデフォルトのプロパティーセットが用意されています。HubSpot上で、またはプロパティーAPIを使用して、独自のカスタムプロパティーを作成および管理することもできます。 プロパティーを作成する際には、データの構築方法を考慮することが重要です。多くの場合、HubSpotの標準オブジェクト上にカスタムプロパティーを作成することで適切に対応できます。しかし場合によっては、独自のプロパティーを備えたカスタムオブジェクトを別途作成することが必要になります。

​
デフォルトのプロパティー

CRMオブジェクトは、1つの主要なtypeと一連のpropertiesによって定義されます。タイプごとに標準のプロパティーセットがあり、名前と値のペアで表されます。 各オブジェクトのデフォルトのプロパティーは以下でご確認いただけます。

​
プロパティーグループ

プロパティーグループは、関連する複数のプロパティーをグループ化するために使用します。グループ化されたプロパティーは各HubSpotレコード上に隣接して表示されます。カスタムオブジェクトのプロパティーを作成して連携を行う場合は、カスタムプロパティーのグループを活用することでデータの特定が容易になります。

​
プロパティーのtypeとfieldTypeの値

プロパティーを作成または更新するには、typeとfieldTypeの両方の値が必要です。typeの値により、プロパティーの型、つまり文字列、数値などのデータ型が決まります。fieldTypeプロパティーでは、HubSpotでのプロパティーの表示形式（プレーンテキスト、ドロップダウンメニュー、日付入力など）を指定します。 以下の表に、プロパティーの有効なtype値とそれに対応するfieldType値を示します。
type説明有効なfieldType値
boolバイナリーオプション（YesまたはNo、TrueまたはFalseなど）を格納するフィールド。booleancheckbox、calculation_equation
enumeration一連のオプションを表す文字列。各オプションはセミコロンで区切ります。booleancheckbox、checkbox、radio、select、calculation_equation
date特定の年月日を表す値。値はUTC時間で表す必要があります。値の形式として、ISO 8601文字列またはミリ秒単位のエポック時間タイムスタンプ（UTC深夜0時）が可能です。date
datetime特定の年月日と時刻を表す値。値はUTC時間で表す必要があります。値の形式として、ISO 8601文字列またはミリ秒単位のUNIXタイムスタンプが可能です。date
stringプレーンテキスト文字列。文字数の上限は65,536文字です。file、text、textarea、calculation_equation、html、phonenumber
number数字から成る、小数第1位までの数値。number、calculation_equation
object_coordinates他のHubSpotオブジェクトを参照するために使用されるテキスト値。内部プロパティーのみに使用されます。このタイプのプロパティーは作成／編集不可であり、HubSpotには表示されません。text
json書式設定されたJSONとして格納されるテキスト値。内部プロパティーにのみ使用されます。このタイプのプロパティーは作成／編集不可であり、HubSpotには表示されません。text
有効なfieldType値について以下に説明します。
fieldType説明
booleancheckboxユーザーが「はい」または「いいえ」のいずれかを選択できる入力。フォーム内で使用する場合、1つのチェックボックスとして表示されます。詳しくは、単一チェックボックスプロパティーに値を追加する方法をご確認ください。
calculation_equation他のプロパティー値や関連付けに基づいて値を計算できるカスタム式。詳しくは、計算プロパティーを定義する方法をご確認ください。
checkboxプロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。詳しくは、複数チェックボックスプロパティーの更新時に値を書式設定する方法をご確認ください。
date日付値。日付入力として表示されます。
fileレコード上またはフォーム経由でのファイルアップロードを許可します。ファイルIDが格納されます。
htmlサニタイズ（エスケープ）されたHTMLとしてレンダリングされる文字列。プロパティーに対するリッチ テキスト エディターの使用が可能になります。
number10進数または科学的表記で記述された、数字の文字列または数値。
phonenumber書式設定された電話番号として表示されるプレーンテキスト文字列。
radioプロパティーで使用可能な選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。
selectプロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。
textプレーンテキスト文字列。単行テキスト入力として表示されます。
textareaプレーンテキスト文字列。単行テキスト入力として表示されます。

​
プロパティーを作成する

プロパティーを作成するには、POSTリクエストを/crm/v3/properties/{objectType}に送信します。リクエスト本文に以下の必須フィールドを含めます。
  • groupName：当該プロパティーが属するプロパティーグループ。
  • name：当該プロパティーの内部名（例：favorite_food）。
  • label：HubSpotに表示される当該プロパティーの名前（例：好きな食べ物）。
  • type：プロパティーの型。
  • fieldType：プロパティーのフィールドタイプ。
例えば、「好きな食べ物」という名前のコンタクトプロパティーを作成する場合、リクエストは以下のようになります。 
{
"groupName": "contactinformation",
"name": "favorite_food",
"label": "Favorite Food",
"type": "string",
"fieldType": "text"
}

​
固有IDプロパティーを作成する

HubSpotでレコードが作成されるときには固有ID（hs_object_id）が自動生成され、これを文字列として扱う必要があります。これらのIDはそのオブジェクトタイプ内でのみ一意です。したがって、コンタクトと会社のIDが同じになる場合があります。コンタクトと会社には、コンタクトのEメールアドレス（email）や会社のドメイン名（domain）など、他にも固有のIDがあります。 場合によっては、複数のレコードで同じ値を入力できないように、独自の固有IDプロパティーを作成することが推奨されます。固有IDプロパティーは、オブジェクト当たり10個まで作成できます。APIを介して一意の値を必要とするプロパティーを作成するには、次の操作を行います。
  • POSTリクエストを/crm/v3/properties/{objectType}に送信します。
  • リクエスト本文でhasUniqueValueフィールドの値をtrueに設定します。
{
"groupName": "dealinformation",
"name": "system_a_unique",
"label": "Unique ID for System A",
"hasUniqueValue": true,
"type": "string",
"fieldType": "text"
}
固有IDプロパティーを作成したら、API呼び出しに使用して特定のレコードを取得することができます。例えば、system_a_uniqueプロパティー値がabcである取引を取得するには、リクエストURLは/crm/v3/objects/deals/abc?idProperty=system_a_uniqueになります。 hs_object_id、email（コンタクト）やdomain（会社）を使用する場合と同じように、この固有IDプロパティーの値を使用して特定のレコードを識別し、更新できます。

​
計算プロパティーを作成する

計算プロパティーは、同じオブジェクトレコード内の他のプロパティーに基づいてプロパティー値を定義します。計算プロパティーを定義するには、最小値、最大値、件数、合計、平均などを求める演算を含めた式を使用します。プロパティーAPIを使用すると、HubSpotアカウント内で計算プロパティーを読み取ったり、フィールドタイプとしてcalculation_equation、データ型としてnumber、bool、string、またはenumerationを使用して計算プロパティーを作成したりできます。 プロパティーの計算式は、calculationFormulaフィールドを使用して定義できます。

​
注：

APIを介して作成された計算プロパティーをHubSpot内で編集することはできません。これらのプロパティーは、プロパティーAPIを介してのみ編集できます。

​
計算プロパティーの構文

calculationFormulaを使用すると、算術演算子、比較演算子、論理演算子、条件文、およびその他の関数を使用して式を記述できます。

​
リテラル構文

  • 文字列リテラル: 定数列を表現するには、単一引用符（'constant'）または二重引用符（"constant"）のいずれかを使用できます。
  • 数値リテラル: 定数には任意の実数を指定でき、小数点表現を含めることもできます。1005と1.5589はどちらも有効な定数です。
  • ブール値リテラル: ブール型定数にはtrueまたはfalseを指定できます。

​
プロパティーの構文

  • 文字列プロパティー変数: 識別文字列を文字列プロパティーとして解釈させるには、それをstring関数でラップする必要があります。例えば、string(var1)は文字列プロパティーvar1として解釈されます。
  • 数値プロパティー変数: 全ての識別子が数値プロパティー変数として解釈されます。例えば、var1は数値プロパティーvar1の値として解釈されます。
  • ブール型プロパティー変数: 識別子をブール型プロパティーとして解釈させるには、それをbool関数でラップする必要があります。例えば、識別子bool(var1)はブール型プロパティーvar1の値として解釈されます。

​
注：

使用される言語では、文字列を除く全てのタイプで大文字と小文字が区別されます。例えばIf A ThEn Bはif a then bとまったく同じですが、'a'と'A'は同じではありません。トークン化にスペース、タブ、改行が使用されますが、無視されます。

​
演算子

演算子は、リテラル値とプロパティー値で使用できます。算術演算子の場合、乗算には接頭辞表記を使用し、演算の順序を指定するには括弧を使用します。
演算子説明例
+数値または文字列を加算します。property1 + 100
-数値を減算します。property1 + 100 - property2
*数値を乗算します。10property1 = 10 * property1
/数値を除算します。property1 * (100 - property2/(50 - property3))
<ある値が別の値より小さいことを確認します。数値プロパティーまたは定数で使用できます。a < 100
>ある値が別の値より大きいことを確認します。数値プロパティーまたは定数で使用できます。a > 50
<=ある値が別の値以下であることを確認します。数値プロパティーまたは定数で使用できます。a <= b
>=ある値が別の値以上であることを確認します。数値プロパティーまたは定数で使用できます。b>= c
=ある値が別の値と等しいことを確認します。数字と文字列の両方で使用できます。(a + b - 100c * 150.652) = 150-230b
equalsある値が別の値と等しいことを確認します。数字と文字列の両方で使用できます。a + b - 100.2c * 150 equals 150 - 230
!=ある値が別の値と等しくないことを確認します。数字と文字列の両方で使用できます。string(property1) != 'test_string'
or2つの値のいずれかまたは両方がtrueであることを確認します。a > b or b <= c
and両方の値がtrueであることを確認します。bool(a) and bool(c)
notいずれの値もtrueでないことを確認します。not (bool(a) and bool(c))

​
関数

サポートされている関数は以下の通りです。
関数説明例
max2個から100個までの入力値を取り、全ての入力値の中から最大値を返します。max(a, b, c, 100)、max(a, b)
min2個から100個までの入力値を取り、全ての入力値の中から最小値を返します。min(a, b, c, 100)、min(a, b)
is_present式を評価できるかどうかを評価します。is_present(bool(a))= true（プロパティーがブール型の場合）is_present(bool(a)) = false（プロパティーが空か、ブール型でない場合）
contains入力として2個の値を取り、最初の入力値に2番目の入力値が含まれている場合はtrueを返します。contains('hello', 'ello') = true、contains('ello', 'hello') = false
concatenate文字列のリストを結合します。リストには、2個から100個までの入力を含めることができます。concatenate('a', 'b', string(a), string(b))
以下の2つの解析関数も使用できます。
  • number_to_string：入力された数値式を文字列に変換しようと試みます。
  • string_to_number：入力された文字列式を数値に変換しようと試みます。
例えば、文字列と数値を加算することはできないため、"Number of cars: " + num_carsは有効なプロパティーではありませんが、"Number of cars: " + number_to_string(num_cars)は有効です。

​
条件文

if、elseif、endif、elseを使った条件文を使用して式を記述することもできます。 例えば、条件文はif boolean_expression then statement [elseif expression then statement]* [else statement | endif]のようになります。ここで、括弧で囲まれた[a]はオプションであることを表し、a|bは「a」または「b」が有効であることを表します。*は0以上であることを意味します。endifを使用すると、条件文を早期に終了して、次のelseifが属するifをパーサーが特定できるようにすることができます。

​
式の例

独自の計算式を定義する際、以下の例を参考にしてください。 
"calculationFormula": "closed - started"
条件文を使用した高度な例を以下に示します。 
"calculationFormula": "if is_present(hs_latest_sequence_enrolled_date) then
  if is_present(hs_sequences_actively_enrolled_count) an hs_sequences_actively_enrolled_count >= 1 then
    true
  else
    false
else
  ''"

​
プロパティーを取得する

オブジェクト内の個々のプロパティーまたは全てのプロパティーの情報を取得することができます。
  • 個々のプロパティーを取得するには、GETリクエストをcrm/v3/properties/{object}/{propertyName}に送信します。例えば、favorite_foodプロパティーを取得する場合のリクエストURLは、/crm/v3/properties/contacts/favorite_foodになります。
  • オブジェクトの全てのプロパティーを取得するには、GETリクエストを/crm/v3/properties/{objectType}に送信します。

​
注：

全てのプロパティーを取得するとき、デフォルトでは非センシティブプロパティーのみが返されます。センシティブデータのプロパティーを取得するには、値をsensitiveに設定したdataSensitivityクエリーパラメーターを含めます。詳しくは、APIを使用したセンシティブデータの管理（ベータ版、Enterprise__のみ）についてご確認ください。

​
プロパティーの値を更新または消去する

レコードのプロパティー値を更新するには、PATCHリクエストをcrm/v3/objects/{objectType}/{recordId}に送信します。リクエスト本文で、以下のプロパティーとその値を配列に格納します。詳しくは、オブジェクトAPIを介したレコードの更新についてご確認ください。

​
日付および日時プロパティーに値を追加する

レスポンスの時刻値はISO 8601形式で表記されますが、HubSpotのAPIでは日付と時刻の値について以下の2つの形式の両方を受け入れます。
  • ISO 8601形式の文字列：データ型に応じて以下のいずれかの形式になります。
    • 特定の日付を表す値の場合、「YYYY-MM-DD」という完全日付形式が使用されます（例：2020-02-29）
    • 特定の日時を表す値の場合、完全な日付形式に時、分、秒、および秒小数部分を追加した「YYYY-MM-DDThh:mm:ss.sTZD」という形式が使用されます：（例：2020-02-29T03:30:17.000Z）。時刻は常にUTCで表現されるため、値には必ずUTC指定子""「Z」が使用されます。
  • UNIX形式のタイムスタンプ（ミリ秒単位）：UTC時間で表されるミリ秒単位のタイムスタンプ値。例えばタイムスタンプ値1427997766000は、「2015年4月2日の18:02:46 UTC」、つまり「2015年4月2日の午後2:02:46 EDT（米国東部夏時間）」を表します。
日付を格納するには2種類のプロパティー（dateとdatetime）が利用でき、これらも値の書式設定方法に影響します。
  • dateプロパティーは、時間ではなく日付を保存します。dateプロパティーには、アカウントやユーザーのタイムゾーン設定に関係なく、設定されている日付が表示されます。dateプロパティー値では、ISO 8601の完全な日付形式を使用することをお勧めします。UNIXタイムスタンプ形式を使用する場合は、エポックミリ秒タイムスタンプを使用する必要があります（つまり、対象となる日付のUTCの深夜の値に設定する必要があります）。例えば、2015年5月1日をそれぞれの形式で表すと以下のようになります。
    • IOS 8601：2015-05-01
    • UNIXミリ秒タイムスタンプ：1430438400000
  • datetimeプロパティーには、日付と時刻の両方が保存されます。両方のタイムスタンプ形式が受け入れられます。HubSpotのdatetimeプロパティーは、レコードを表示するユーザーのタイムゾーンに基づいて表示されるため、値はユーザーの現地タイムゾーンに変換されます。

​
チェックボックスタイプのプロパティーに値を追加する

レコードのチェックボックスタイプのプロパティーの値を更新する場合は、以下の方法で値を書式設定します。
  • ブール型チェックボックスプロパティー：HubSpotで「はい」と表示するか、チェックが入った状態にするには、値がtrueである必要があります。HubSpotで［いいえ］として表示するか、チェックが入っていない状態にするには、値がfalseである必要があります。
  • 複数選択チェックボックスプロパティー：複数チェックボックスプロパティーに値を追加するには、最初の値の前にセミコロンを追加し、値ごとにセミコロンで区切ります。値とセミコロンの間にはスペースを入れないでください。プロパティーに既に値がある場合、先頭のセミコロンによって値が上書きされるのではなく、値が付加されます。例えば、コンタクトのhs_buying_roleプロパティーに既存の値としてDECISION_MAKERが格納されているとします。既存の値を置き換えずに追加の値を付加する場合、リクエストは以下のようになります。
{
"properties": {
"hs_buying_role": ";BUDGET_HOLDER;END_USER"
}
}

​
ユーザープロパティーでレコード所有者を割り当てる

APIを介してCRMレコードにユーザーを割り当てるには、値としてユーザーの所有者idを指定する必要があります。所有者IDは、プロパティー設定または所有者APIを介して確認できます。例えば、ユーザーをコンタクトの所有者として割り当てるには、PATCHリクエストの本文に{ "properties":{ "hubspot_owner_id": "41629779"}}を設定してcrm/v3/objects/contacts/{contactId}に送信します。

​
プロパティー値を消去する

APIを介してオブジェクトプロパティーの値を消去するには、プロパティー値を空の文字列に設定します。 例えば、コンタクトオブジェクトからfirstnameを消去するには、PATCHリクエストの本文に{ "properties": { "firstname": ""}}を指定して/crm/v3/objects/contacts/{contactId}に送信します。