HubSpotのコンタクトレコードには、自社とやりとりする個人に関する情報が保存されます。コンタクトエンドポイントを使用することにより、HubSpotアカウントでコンタクトレコードを作成および管理したり、HubSpotと他のシステムの間でコンタクトデータを同期したりできます。
オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、「CRMについて」のガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。
コンタクトを作成する
新しいコンタクトを作成するには、POSTリクエストを/crm/v3/objects/contactsに送信します。
リクエスト内のプロパティーオブジェクトにコンタクトデータを含めます。また、関連付けオブジェクトを追加して、新しいコンタクトを既存のレコード（会社、取引など）やアクティビティー（ミーティング、メモなど）に関連付けることもできます。
プロパティー
コンタクトの詳細は、コンタクトプロパティーに保存されます。HubSpotのデフォルトのコンタクトプロパティーがありますが、カスタムのコンタクトプロパティーを作成することもできます。
新しいコンタクトを作成する際は、email、firstname、またはlastnameプロパティーのうち、少なくとも1つをリクエストに含める必要があります。Eメールアドレスはコンタクトを一意に識別する主要なIDであるため、HubSpotでコンタクトが重複しないようにするために、常にemailを含めることを推奨します。
利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/contactsに送信することで、アカウントのコンタクトプロパティーのリストを取得できます。詳しくはプロパティーAPIをご参照ください。
リクエストにlifecyclestageを含める場合、値はライフサイクルステージの内部名を参照する必要があります。デフォルトのステージの内部名はテキスト値であり、ステージのラベル（subscriberやmarketingqualifiedleadなど）を編集しても変更されません。カスタムステージの内部名は数値です。ステージの内部IDは、ライフサイクルステージ設定か、API経由でライフサイクルステージプロパティーを取得することで確認できます。 ///Example request body
{
"properties": {
"email": "[email protected]",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
}
}
関連付け
また、新しいコンタクトを作成する際に関連付けオブジェクトを含めることで、そのコンタクトを既存のレコードやアクティビティーに関連付けることもできます。例えば、新しいコンタクトを既存の会社レコードとEメールに関連付ける場合、リクエストの内容は次のようになります。
///Example request body
{
"properties": {
"email": "[email protected]",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"company": "HubSpot",
"website": "hubspot.com",
"lifecyclestage": "marketingqualifiedlead"
},
"associations": [
{
"to": {
"id": 123456
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 279
}
]
},
{
"to": {
"id": 556677
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 197
}
]
}
]
}
| パラメーター | 説明 |
|---|
to | コンタクトに関連付けるレコードまたはアクティビティー。一意のid値で指定します。 |
types | コンタクトとレコードまたはアクティビティー間の関連付けのタイプであるassociationCategoryとassociationTypeIdを含めます。デフォルトの関連付けタイプIDはこちらのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ（ラベル）の値を取得することもできます。 |
レコードID、Eメール、またはカスタムの固有値のプロパティーを指定してコンタクトを取得する
コンタクトレコードを個別に、または一括で取得できます。
- 個々のコンタクトを取得するには、
GETリクエストを/crm/v3/objects/contacts/{contactId} orまたは/crm/v3/objects/contacts/{email}?idProperty=emailに送信します。
- 全てのコンタクトリストを取得するには
GETリクエストを/crm/v3/objects/contactsに送信します。
これらのエンドポイントに対し、リクエストのURLに次のクエリーパラメーターを含めることができます。
| パラメーター | 説明 |
|---|
properties | レスポンスで返されるプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
propertiesWithHistory | レスポンスで返される現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
associations | 関連付けられたIDを取得する対象のオブジェクトのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。 |
- レコードID、Eメールアドレス、またはカスタムの固有の識別子のプロパティーを指定して、特定のコンタクトを一括で取得するには
POSTリクエストをcrm/v3/objects/contacts/batch/readに送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。
一括読み取りエンドポイントの場合は、任意指定のidPropertyパラメーターを使用し、emailまたはカスタムの固有の識別子のプロパティーを指定して、コンタクトを取得することもできます。デフォルトで、リクエストのid値はレコードID（hs_object_id）を参照するため、レコードIDを使って取得するときにはidPropertyパラメーターは不要です。emailまたはカスタムの固有の値のプロパティーを使用してコンタクトを取得する場合は、idPropertyパラメーターを含める必要があります。
例えば、レコードIDの値に基づいてコンタクトを一括で取得する場合のリクエストは、次のようになります（現在の値のみ、または現在と過去の値）。
Eメールアドレスまたはカスタムの固有の識別子のプロパティー（例：自社に固有の顧客ID番号）に基づいてコンタクトレコードを取得する場合のリクエストは、次のようになります。
コンタクトを更新する
コンタクトレコードを個別に、または一括で更新できます。
個別の
コンタクトを更新するには、レコードID（id）またはコンタクトのEメールアドレス（email）を使用します。
- レコードIDを基準に個別のコンタクトを更新するには、
PATCHリクエストを/crm/v3/objects/contacts/{contactId}に送信し、更新対象のデータを含めます。
- Eメールを基準に個別のコンタクトを更新するには、
PATCHリクエストを/crm/v3/objects/contacts/{email}?idProperty=emailに送信し、更新対象のデータを含めます。
以下に例を示します。
{
"properties": {
"favorite_food": "burger",
"jobtitle": "Manager",
"lifecyclestage": "Customer"
}
}
lifecyclestageプロパティーを更新する場合、ライフサイクルステージの先のステージにのみ値を設定できます。ライフサイクルステージの前のステージに設定するには、まずレコードの既存のライフサイクルステージの値をクリアする必要があります。この値は手動でクリアできます。または、ワークフローやコンタクトデータを同期する連携機能によってこの値を自動的にクリアすることもできます。id）を使用できます。複数のコンタクトを更新するには、POSTリクエストを/crm/v3/objects/contacts/batch/updateに送信します。リクエスト本文に、各コンタクトのレコードIDをidとして含め、更新対象のプロパティーを含めます。
以下に例を示します。
{
"inputs": [
{
"id": "123456789",
"properties": {
"favorite_food": "burger"
}
},
{
"id": "56789123",
"properties": {
"favorite_food": "Donut"
}
}
]
}
コンタクトを一括更新する
一括更新エンドポイントを使用して、一括でコンタクトを作成し、同時に更新することもできます。このエンドポイントでは、emailまたはカスタムの固有IDプロパティーを使用できます。リクエストに従って、コンタクトがすでに存在する場合は更新され、コンタクトが存在しない場合は作成されます。
コンタクトを一括更新するには、POSTリクエストを/crm/v3/objects/contacts/batch/upsertに送信します。リクエスト本文にidPropertyパラメーターを含め、emailまたはカスタムの固有IDプロパティーのどちらを使用しているかを識別します。そのプロパティーの値をidとして含め、設定または更新する他のプロパティーを追加します。
emailをコンタクトのidPropertyとして使用する場合、部分的なアップサート（更新または挿入）はサポートされません。部分的なアップサートを実行するには、代わりにカスタムの固有IDプロパティーをidPropertyとして使用します。{
"inputs": [
{
"properties": {
"phone": "+18884827768"
},
"id": "[email protected]",
"idProperty": "email"
},
{
"properties": {
"phone": "+18888888888"
},
"id": "[email protected]",
"idProperty": "email"
}
]
}
既存のコンタクトを他のレコードまたはアクティビティーに関連付ける
コンタクトを他のCRMレコードまたはアクティビティーに関連付けるには、PUTリクエストを/crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。
associationTypeId値を取得するには、デフォルト値リストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。関連付けを削除する
コンタクトとレコードまたはアクティビティーの間の関連付けを削除するには、DELETEリクエストを/crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。
コンタクトレコードでアクティビティーをピン留めする
リクエストにhs_pinned_engagement_idフィールドを含めることで、コンタクトレコードでアクティビティーをピン留めできます。フィールドに、ピン留めするアクティビティーのidを含めます。このIDは、エンゲージメントAPIを介して取得できます。レコードごとに1つのアクティビティーをピン留めすることができ、そのアクティビティーはピン留めする前に既にコンタクトに関連付けられている必要があります。
コンタクトのピン留めされたアクティビティーを設定または更新するリクエストは、次のようになります。
{
"properties": {
"hs_pinned_engagement_id": 123456789
}
}
{
"properties": {
"email": "[email protected]",
"firstname": "Jane",
"lastname": "Doe",
"phone": "+18884827768",
"hs_pinned_engagement_id": 123456789
},
"associations": [
{
"to": {
"id": 123456789
},
"types": [
{
"associationCategory": "HUBSPOT_DEFINED",
"associationTypeId": 201
}
]
}
]
}
コンタクトを削除する
コンタクトレコードを個別に、または一括で削除できます。削除したコンタクトレコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内でコンタクトを復元できます。
IDを基準に個々のコンタクトを削除するには、DELETEリクエストを/crm/v3/objects/contacts/{contactId}に送信します。
コンタクトを一括で削除する方法については、こちらの資料をご確認ください。
追加のEメール
追加のEメールアドレスは、コンタクトが複数のEメールを持っている場合に使用されます。HubSpotのコンタクトレコードに手動で追加することも、コンタクトのマージ後に自動的に追加することもできます。追加のEメールアドレスは引き続きコンタクトの一意の識別子であるため、複数のコンタクトに同じ追加のEメールアドレスを登録することはできません。
コンタクトの追加のEメールアドレスを表示するには、全てまたは個々のコンタクトを取得するときに、propertiesパラメーターにemailとhs_additional_emailsのプロパティーを含めます。コンタクトのプライマリーEメールアドレスはemailフィールドに表示され、追加のEメールアドレスはhs_additional_emailsフィールドに表示されます。
一括処理は、一度に100件のレコードに制限されています。例えば、1つのリクエストで100件を超えるコンタクトを一括で更新することはできません。コンタクトとフォーム送信にも上限があります。 Last modified on December 10, 2025
