> ## 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 | プロパティー

export const postmanIcon = <svg xmlns="http://www.w3.org/2000/svg" width={25} height={25} preserveAspectRatio="xMidYMid" viewBox="0 0 256 256">
    <path fill="#FF6C37" d="M254.953 144.253c8.959-70.131-40.569-134.248-110.572-143.206C74.378-7.912 10.005 41.616 1.047 111.619c-8.959 70.003 40.569 134.248 110.572 143.334 70.131 8.959 134.248-40.569 143.334-110.7Z" />
    <path fill="#FFF" d="m174.2 82.184-54.007 54.007-15.229-15.23c53.11-53.11 58.358-48.503 69.236-38.777Z" />
    <path fill="#FF6C37" d="M120.193 137.47c-.384 0-.64-.128-.895-.384l-15.358-15.229a1.237 1.237 0 0 1 0-1.792c54.007-54.006 59.638-48.887 71.028-38.649.255.256.383.512.383.896s-.128.64-.383.896l-54.007 53.878c-.128.256-.512.384-.768.384Zm-13.437-16.509 13.437 13.438 52.087-52.087c-9.47-8.446-15.87-11.006-65.524 38.65Z" />
    <path fill="#FFF" d="m135.679 151.676-14.718-14.718 54.007-54.006c14.46 14.59-7.167 38.265-39.29 68.724Z" />
    <path fill="#FF6C37" d="M135.679 152.956c-.384 0-.64-.128-.896-.384l-14.718-14.718c-.256-.256-.256-.512-.256-.896s.128-.64.384-.895L174.2 82.056a1.237 1.237 0 0 1 1.791 0 15.58 15.58 0 0 1 4.991 11.902c-.256 14.206-16.38 32.25-44.28 58.614-.383.256-.767.384-1.023.384Zm-12.926-15.998c8.19 8.319 11.646 11.646 12.926 12.926 21.5-20.476 42.36-41.464 42.488-55.926.128-3.327-1.152-6.655-3.327-9.214l-52.087 52.214Z" />
    <path fill="#FFF" d="m105.22 121.345 10.878 10.878c.256.256.256.512 0 .768-.128.128-.128.128-.256.128l-22.524 4.863c-1.152.128-2.175-.64-2.431-1.791-.128-.64.128-1.28.512-1.664l13.053-13.054c.256-.256.64-.384.768-.128Z" />
    <path fill="#FF6C37" d="M92.934 139.262c-1.92 0-3.327-1.536-3.327-3.455 0-.896.384-1.792 1.024-2.432l13.053-13.054c.768-.64 1.792-.64 2.56 0l10.878 10.878c.768.64.768 1.792 0 2.56-.256.256-.512.384-.896.512l-22.524 4.863c-.256 0-.512.128-.768.128Zm11.902-16.51-12.542 12.543c-.256.256-.383.64-.128 1.024.128.383.512.511.896.383l21.116-4.607-9.342-9.342Z" />
    <path fill="#FFF" d="M202.739 52.238c-8.191-7.935-21.373-7.679-29.307.64-7.935 8.318-7.679 21.372.64 29.306A20.678 20.678 0 0 0 199.155 85l-14.59-14.59 18.174-18.172Z" />
    <path fill="#FF6C37" d="M188.405 89.223c-12.158 0-22.012-9.854-22.012-22.012 0-12.158 9.854-22.012 22.012-22.012 5.631 0 11.134 2.176 15.23 6.143.255.256.383.512.383.896s-.128.64-.384.895L186.357 70.41l13.566 13.566c.512.512.512 1.28 0 1.792l-.256.256c-3.327 2.047-7.295 3.199-11.262 3.199Zm0-41.337c-10.75 0-19.452 8.703-19.324 19.453 0 10.75 8.702 19.452 19.452 19.324 2.944 0 5.887-.64 8.575-2.047l-13.438-13.31c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l17.149-17.15c-3.456-2.943-7.807-4.479-12.414-4.479Z" />
    <path fill="#FFF" d="m203.122 52.622-.255-.256-18.301 18.044 14.461 14.462c1.408-.896 2.816-1.92 3.967-3.072a20.51 20.51 0 0 0 .128-29.178Z" />
    <path fill="#FF6C37" d="M199.155 86.28c-.384 0-.64-.128-.896-.384l-14.589-14.59c-.256-.256-.384-.512-.384-.896s.128-.64.384-.895l18.173-18.173a1.237 1.237 0 0 1 1.791 0l.384.256c8.575 8.574 8.575 22.396.128 31.098-1.28 1.28-2.687 2.432-4.223 3.328-.384.128-.64.256-.768.256Zm-12.798-15.87 12.926 12.926c1.024-.64 2.048-1.536 2.816-2.304 7.294-7.294 7.678-19.196.64-26.875L186.357 70.41Z" />
    <path fill="#FFF" d="M176.375 84.488a7.879 7.879 0 0 0-11.134 0l-48.247 48.247 8.063 8.063 51.062-44.792c3.328-2.816 3.584-7.807.768-11.134-.256-.128-.384-.256-.512-.384Z" />
    <path fill="#FF6C37" d="M124.929 142.077c-.384 0-.64-.128-.896-.383l-8.063-8.063a1.237 1.237 0 0 1 0-1.792l48.247-48.247a9.115 9.115 0 0 1 12.926 0 9.115 9.115 0 0 1 0 12.926l-.384.384-51.063 44.792c-.128.255-.384.383-.767.383Zm-6.143-9.342 6.27 6.271 50.167-44.024c2.816-2.304 3.072-6.527.768-9.342-2.303-2.816-6.526-3.072-9.342-.768-.128.128-.256.256-.512.384l-47.351 47.48Z" />
    <path fill="#FFF" d="M80.009 187.637c-.512.256-.768.768-.64 1.28l2.175 9.214c.512 1.28-.256 2.816-1.663 3.2-1.024.384-2.176 0-2.816-.768l-14.077-13.95 45.943-45.943 15.87.256 10.75 10.75c-2.56 2.175-18.045 17.149-55.542 35.961Z" />
    <path fill="#FF6C37" d="M78.985 202.61c-1.024 0-2.048-.383-2.688-1.151l-13.95-13.95c-.255-.256-.383-.512-.383-.896 0-.383.128-.64.384-.895l45.944-45.944c.256-.256.64-.384.895-.384l15.87.256c.383 0 .64.128.895.384l10.75 10.75c.256.256.384.64.384 1.024s-.128.64-.512.896l-.895.767c-13.566 11.902-31.995 23.804-54.902 35.194l2.175 9.086c.384 1.664-.384 3.456-1.92 4.352-.767.384-1.407.512-2.047.512Zm-14.078-15.997 13.182 13.054c.384.64 1.152.896 1.792.512.64-.384.896-1.152.512-1.792l-2.176-9.214c-.256-1.152.256-2.176 1.28-2.688 22.652-11.39 40.952-23.163 54.39-34.81l-9.47-9.47-14.718-.256-44.792 44.664Z" />
    <path fill="#FFF" d="m52.11 197.62 11.006-11.007 16.38 16.381-26.107-1.791c-1.151-.128-1.92-1.152-1.791-2.304 0-.512.128-1.024.512-1.28Z" />
    <path fill="#FF6C37" d="m79.497 204.146-26.236-1.791c-1.92-.128-3.199-1.792-3.071-3.712.128-.768.384-1.535 1.024-2.047L62.22 185.59a1.237 1.237 0 0 1 1.792 0l16.38 16.38c.385.385.512.897.257 1.408-.256.512-.64.768-1.152.768Zm-16.381-15.74-10.11 10.11c-.384.255-.384.895 0 1.151.127.128.255.256.511.256l22.652 1.536-13.053-13.054ZM104.452 146.557c-.768 0-1.28-.64-1.28-1.28 0-.384.128-.64.384-.896l12.414-12.414a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-20.477 4.352h-.256Zm12.414-11.902-8.446 8.446 13.821-2.943-5.375-5.503Z" />
    <path fill="#FFF" d="m124.8 140.926-14.077 3.071c-1.024.256-2.048-.384-2.303-1.408-.128-.64 0-1.28.511-1.791l7.807-7.807 8.063 7.935Z" />
    <path fill="#FF6C37" d="M110.467 145.277a3.168 3.168 0 0 1-3.2-3.2c0-.895.385-1.663.897-2.303l7.806-7.807a1.237 1.237 0 0 1 1.792 0l8.062 8.063c.384.384.512.768.384 1.28-.128.384-.512.767-1.023.895l-14.078 3.072h-.64Zm6.399-10.622-6.91 6.91c-.257.257-.257.512-.129.768s.384.384.768.384l11.774-2.56-5.503-5.502ZM203.25 64.907c-.256-.767-1.151-1.151-1.92-.895-.767.255-1.151 1.151-.895 1.92 0 .127.128.255.128.383.768 1.536.512 3.455-.512 4.863-.512.64-.384 1.536.128 2.048.64.512 1.536.384 2.048-.256 1.92-2.432 2.303-5.503 1.023-8.063Z" />
  </svg>;

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<Card title="Run in Postman" href="https://app.getpostman.com/run-collection/33493e154afc38038092" icon={postmanIcon} horizontal={true} />

<RelatedApiLink />

プロパティーは、CRMレコードに情報を格納するために使用します。HubSpotでは、CRMオブジェクトごとにデフォルトのプロパティーセットが用意されています。[HubSpot上で](https://knowledge.hubspot.com/ja/properties/create-and-edit-properties)、またはプロパティーAPIを使用して、独自のカスタムプロパティーを作成および管理することもできます。

プロパティーを作成する際には、データの構築方法を考慮することが重要です。多くの場合、HubSpotの標準オブジェクト上にカスタムプロパティーを作成することで適切に対応できます。しかし場合によっては、独自のプロパティーを備えた[カスタムオブジェクト](/api-reference/crm-custom-objects-v3/guide)を別途作成することが必要になります。

<Accordion title="スコープ要件">
  <ScopesList
    scopes={[
  'automation',
  'crm.objects.appointments.read',
  'crm.objects.appointments.sensitive.read.v2',
  'crm.objects.appointments.sensitive.write.v2',
  'crm.objects.appointments.write',
  'crm.objects.carts.read',
  'crm.objects.carts.write',
  'crm.objects.commercepayments.write',
  'crm.objects.companies.highly_sensitive.read.v2',
  'crm.objects.companies.highly_sensitive.write.v2',
  'crm.objects.companies.read',
  'crm.objects.companies.sensitive.read.v2',
  'crm.objects.companies.sensitive.write.v2',
  'crm.objects.companies.write',
  'crm.objects.contacts.highly_sensitive.read.v2',
  'crm.objects.contacts.highly_sensitive.write.v2',
  'crm.objects.contacts.read',
  'crm.objects.contacts.sensitive.read.v2',
  'crm.objects.contacts.sensitive.write.v2',
  'crm.objects.contacts.write',
  'crm.objects.courses.read',
  'crm.objects.courses.write',
  'crm.objects.custom.highly_sensitive.read.v2',
  'crm.objects.custom.highly_sensitive.write.v2',
  'crm.objects.custom.read',
  'crm.objects.custom.sensitive.read.v2',
  'crm.objects.custom.sensitive.write.v2',
  'crm.objects.custom.write',
  'crm.objects.deals.highly_sensitive.read.v2',
  'crm.objects.deals.highly_sensitive.write.v2',
  'crm.objects.deals.read',
  'crm.objects.deals.sensitive.read.v2',
  'crm.objects.deals.sensitive.write.v2',
  'crm.objects.deals.write',
  'crm.objects.feedback_submissions.read',
  'crm.objects.goals.read',
  'crm.objects.goals.write',
  'crm.objects.invoices.read',
  'crm.objects.invoices.write',
  'crm.objects.leads.read',
  'crm.objects.leads.write',
  'crm.objects.line_items.read',
  'crm.objects.line_items.write',
  'crm.objects.listings.read',
  'crm.objects.listings.write',
  'crm.objects.marketing_events.read',
  'crm.objects.marketing_events.write',
  'crm.objects.orders.read',
  'crm.objects.orders.write',
  'crm.objects.owners.read',
  'crm.objects.products.write',
  'crm.objects.quotes.read',
  'crm.objects.quotes.write',
  'crm.objects.services.read',
  'crm.objects.services.write',
  'crm.objects.subscriptions.read',
  'crm.objects.subscriptions.write',
  'crm.objects.users.read',
  'crm.objects.users.write',
  'crm.pipelines.orders.read',
  'crm.pipelines.orders.write',
  'crm.schemas.appointments.read',
  'crm.schemas.appointments.write',
  'crm.schemas.carts.read',
  'crm.schemas.carts.write',
  'crm.schemas.commercepayments.read',
  'crm.schemas.commercepayments.write',
  'crm.schemas.companies.read',
  'crm.schemas.companies.write',
  'crm.schemas.contacts.read',
  'crm.schemas.contacts.write',
  'crm.schemas.courses.read',
  'crm.schemas.courses.write',
  'crm.schemas.custom.read',
  'crm.schemas.deals.read',
  'crm.schemas.deals.write',
  'crm.schemas.invoices.read',
  'crm.schemas.invoices.write',
  'crm.schemas.line_items.read',
  'crm.schemas.listings.read',
  'crm.schemas.listings.write',
  'crm.schemas.orders.read',
  'crm.schemas.orders.write',
  'crm.schemas.quotes.read',
  'crm.schemas.services.read',
  'crm.schemas.services.write',
  'crm.schemas.subscriptions.read',
  'crm.schemas.subscriptions.write',
  'e-commerce',
  'media_bridge.read',
  'tickets',
  'tickets.highly_sensitive.v2',
  'tickets.sensitive.v2',
  'timeline'
]}
  />
</Accordion>

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

CRMオブジェクトは、1つの主要な`type`と一連の`properties`によって定義されます。タイプごとに標準のプロパティーセットがあり、名前と値のペアで表されます。

各オブジェクトのデフォルトのプロパティーは以下でご確認いただけます。

* [コンタクト](https://knowledge.hubspot.com/ja/properties/hubspots-default-contact-properties)
* [会社](https://knowledge.hubspot.com/ja/properties/hubspot-crm-default-company-properties)
* [取引](https://knowledge.hubspot.com/ja/properties/hubspots-default-deal-properties)
* [チケット](https://knowledge.hubspot.com/ja/properties/hubspots-default-ticket-properties)
* [アクティビティー](https://knowledge.hubspot.com/ja/properties/hubspots-default-activity-properties)（コール、Eメール、ミーティング、メモ、タスク）
* [リード](https://knowledge.hubspot.com/ja/properties/hubspots-default-lead-properties)（**Sales Hub** **ProfessionalおよびEnterprise**）

## プロパティーグループ

プロパティー[グループ](https://knowledge.hubspot.com/ja/properties/create-and-edit-properties#create-and-edit-property-groups)は、関連する複数のプロパティーをグループ化するために使用します。グループ化されたプロパティーは各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文字列またはミリ秒単位のエポック時間タイムスタンプ](#add-values-to-date-and-datetime-properties)（UTC深夜0時）が可能です。 | `date`                                                               |
| `datetime`           | 特定の年月日と時刻を表す値。値はUTC時間で表す必要があります。値の形式として、[ISO 8601文字列またはミリ秒単位のUNIXタイムスタンプ](#add-values-to-date-and-datetime-properties)が可能です。         | `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つのチェックボックスとして表示されます。詳しくは、[単一チェックボックスプロパティーに値を追加する方法](#add-values-to-checkbox-type-properties)をご確認ください。 |
| `calculation_equation` | 他のプロパティー値や関連付けに基づいて値を計算できるカスタム式。詳しくは、[計算プロパティー](#create-calculation-properties)を定義する方法をご確認ください。                                                     |
| `checkbox`             | プロパティー内で使用可能な選択肢の中からユーザーが複数選択できるチェックボックスのリスト。詳しくは、[複数チェックボックスプロパティーの更新時に値を書式設定する方法](#add-values-to-checkbox-type-properties)をご確認ください。               |
| `date`                 | 日付値。日付入力として表示されます。                                                                                                                                  |
| `file`                 | レコード上またはフォーム経由でのファイルアップロードを許可します。ファイルIDが格納されます。                                                                                                     |
| `html`                 | サニタイズ（エスケープ）されたHTMLとしてレンダリングされる文字列。プロパティーに対するリッチ テキスト エディターの使用が可能になります。                                                                             |
| `number`               | 10進数または科学的表記で記述された、数字の文字列または数値。                                                                                                                     |
| `phonenumber`          | 書式設定された電話番号として表示されるプレーンテキスト文字列。                                                                                                                     |
| `radio`                | プロパティーで使用可能な選択肢の中からユーザーがいずれか1つを選択できる入力。フォーム内で使用する場合、一連のラジオボタンとして表示されます。                                                                             |
| `select`               | プロパティーで許容される選択肢の中からユーザーがいずれか1つを選択できるドロップダウンの入力。                                                                                                     |
| `text`                 | プレーンテキスト文字列。単行テキスト入力として表示されます。                                                                                                                      |
| `textarea`             | プレーンテキスト文字列。単行テキスト入力として表示されます。                                                                                                                      |

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

プロパティーを作成するには、`POST`リクエストを`/crm/v3/properties/{objectType}`に送信します。リクエスト本文に以下の必須フィールドを含めます。

* `groupName`：当該プロパティーが属する[プロパティーグループ](https://knowledge.hubspot.com/ja/properties/organize-and-export-properties)。
* `name`：当該プロパティーの内部名（例：favorite\_food）。
* `label`：HubSpotに表示される当該プロパティーの名前（例：好きな食べ物）。
* `type`：プロパティーの[型](#property-type-and-fieldtype-values)。
* `fieldType`：プロパティーの[フィールドタイプ](#property-type-and-fieldtype-values)。

例えば、「好きな食べ物」という名前のコンタクトプロパティーを作成する場合、リクエストは以下のようになります。

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "groupName": "contactinformation",
      "name": "favorite_food",
      "label": "Favorite Food",
      "type": "string",
      "fieldType": "text"
    }
    ```
  </Tab>
</Tabs>

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

HubSpotでレコードが作成されるときには固有ID（`hs_object_id`）が自動生成され、これを文字列として扱う必要があります。これらのIDはそのオブジェクトタイプ内でのみ一意です。したがって、コンタクトと会社のIDが同じになる場合があります。コンタクトと会社には、コンタクトのEメールアドレス（`email`）や会社のドメイン名（`domain`）など、他にも固有のIDがあります。

場合によっては、複数のレコードで同じ値を入力できないように、独自の固有IDプロパティーを作成することが推奨されます。固有IDプロパティーは、オブジェクト当たり10個まで作成できます。APIを介して一意の値を必要とするプロパティーを作成するには、次の操作を行います。

* `POST`リクエストを`/crm/v3/properties/{objectType}`に送信します。
* リクエスト本文で`hasUniqueValue`フィールドの値を`true`に設定します。

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "groupName": "dealinformation",
      "name": "system_a_unique",
      "label": "Unique ID for System A",
      "hasUniqueValue": true,
      "type": "string",
      "fieldType": "text"
    }
    ```
  </Tab>
</Tabs>

固有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`フィールドを使用して定義できます。

<Warning>
  ### 注：

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

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

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

#### リテラル構文

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

#### プロパティーの構文

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

<Warning>
  ### 注：

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

#### 演算子

演算子は、リテラル値とプロパティー値で使用できます。算術演算子の場合、乗算には接頭辞表記を使用し、演算の順序を指定するには括弧を使用します。

| 演算子      | 説明                                         | 例                                                |
| -------- | ------------------------------------------ | ------------------------------------------------ |
| `+`      | 数値または文字列を加算します。                            | `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'`             |
| `or`     | 2つの値のいずれかまたは両方がtrueであることを確認します。            | `a > b or b <= c`                                |
| `and`    | 両方の値がtrueであることを確認します。                      | `bool(a) and bool(c)`                            |
| `not`    | いずれの値もtrueでないことを確認します。                     | `not (bool(a) and bool(c))`                      |

#### 関数

サポートされている関数は以下の通りです。

| 関数            | 説明                                              | 例                                                                                             |
| ------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `max`         | 2個から100個までの入力値を取り、全ての入力値の中から最大値を返します。           | `max(a, b, c, 100)`、`max(a, b)`                                                               |
| `min`         | 2個から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`をパーサーが特定できるようにすることができます。

### 式の例

独自の計算式を定義する際、以下の例を参考にしてください。

```json theme={null}
"calculationFormula": "closed - started"
```

条件文を使用した高度な例を以下に示します。

```json theme={null}
"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}`に送信します。

<Warning>
  ### 注：

  全てのプロパティーを取得するとき、デフォルトでは非センシティブプロパティーのみが返されます。センシティブデータのプロパティーを取得するには、値を`sensitive`に設定した`dataSensitivity`クエリーパラメーターを含めます。詳しくは、[APIを使用したセンシティブデータの管理](https://developers.hubspot.jp/docs/reference/api/crm/sensitive-data#manage-sensitive-data)（ベータ版、Enterprise\_\_のみ）についてご確認ください。
</Warning>

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

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

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

レスポンスの時刻値は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`プロパティーは、時間<u>ではなく</u>日付を保存します。`date`プロパティーには、アカウントやユーザーのタイムゾーン設定に関係なく、設定されている日付が表示されます。`date`プロパティー値では、ISO 8601の完全な日付形式を使用することをお勧めします。UNIXタイムスタンプ形式を使用する場合は、エポックミリ秒タイムスタンプを使用する必要があります（つまり、対象となる日付のUTCの深夜の値に設定する必要があります）。例えば、2015年5月1日をそれぞれの形式で表すと以下のようになります。
  * **IOS 8601**：2015-05-01
  * **UNIXミリ秒タイムスタンプ**：1430438400000
* `datetime`プロパティーには、日付と時刻の<u>両方</u>が保存されます。両方のタイムスタンプ形式が受け入れられます。HubSpotの`datetime`プロパティーは、レコードを表示するユーザーのタイムゾーンに基づいて表示されるため、値はユーザーの現地タイムゾーンに変換されます。

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

レコードのチェックボックスタイプのプロパティーの値を更新する場合は、以下の方法で値を書式設定します。

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

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    {
      "properties": {
        "hs_buying_role": ";BUDGET_HOLDER;END_USER"
      }
    }
    ```
  </Tab>
</Tabs>

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

APIを介してCRMレコードにユーザーを割り当てるには、値としてユーザーの所有者`id`を指定する必要があります。所有者IDは、[プロパティー設定](https://knowledge.hubspot.com/ja/properties/create-and-edit-properties)または[所有者API](/api-reference/crm-crm-owners-v3/guide)を介して確認できます。例えば、ユーザーをコンタクトの所有者として割り当てるには、`PATCH`リクエストの本文に`{ "properties":{ "hubspot_owner_id": "41629779"}}`を設定して`crm/v3/objects/contacts/{contactId}`に送信します。

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

APIを介してオブジェクトプロパティーの値を消去するには、プロパティー値を空の文字列に設定します。

例えば、コンタクトオブジェクトから`firstname`を消去するには、`PATCH`リクエストの本文に`{ "properties": { "firstname": ""}}`を指定して`/crm/v3/objects/contacts/{contactId}`に送信します。