コンタクト

概要エンドポイント

HubSpotのコンタクトレコードには、自社とやり取りする個人に関する情報が保存されます。コンタクトエンドポイントを使用することにより、HubSpotアカウントでコンタクトレコードを作成および管理したり、HubSpotと他のシステムの間でコンタクトデータを同期したりできます。

オブジェクト、レコード、プロパティー、および関連付けAPIの詳細については、「CRMについて」のガイドをご確認ください。HubSpotのオブジェクトとレコードに関する一般的な情報については、CRMデータベースを管理する方法をご確認ください。

コンタクトを作成する

新しいコンタクトを作成するには、POSTリクエストを/crm/v3/objects/contactsに送信します。

リクエスト内のpropertiesオブジェクトにコンタクトデータを含めます。また、associationsオブジェクトを追加して、新しいコンタクトを既存のレコード（会社、取引など）やアクティビティー（ミーティング、メモなど）に関連付けることもできます。

プロパティー

コンタクトの詳細は、コンタクトプロパティーに保存されます。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": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "company": "HubSpot", "website": "hubspot.com", "lifecyclestage": "marketingqualifiedlead" } }

関連付け

また、新しいコンタクトを作成する際に、そのコンタクトを既存のレコードやアクティビティーに関連付けることもできます。associationsオブジェクトに、次のフィールドを含めます。

Use this table to describe parameters / fields
ParameterDescription
toObjectId

コンタクトに関連付けるレコードまたはアクティビティーのID。

associationTypeId

コンタクトと他のオブジェクトまたはアクティビティーとの関連付けタイプを示す一意の識別子。既定の関連付けタイプは、ここにリストされています。または、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信して値を取得することもできます。詳しくは関連付けAPIを参照してください。

さらに、labelフィールドを含めて、関連付けについて説明する定義済み関連付けラベルを割り当てることもできます。レコードを関連付ける方法については関連付けAPIをご確認ください。

例えば、新しいコンタクトを既存の会社とEメールに関連付ける場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "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 } ] }] }

コンタクトレコードを取得する

コンタクトレコードを個別に、または一括で取得できます。

  • 個々のコンタクトレコードを取得するには、GETリクエストを/crm/v3/objects/contacts/{contactId}に送信します。
  • 全てのコンタクトレコードのリストを取得するには、GETリクエストを/crm/v3/objects/contactsに送信します。

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

Use this table to describe parameters / fields
ParameterDescription
properties

レスポンスで取得するプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

propertiesWithHistory

レスポンスで取得する現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。

associations

関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。
  • レコードID、Eメールアドレス、またはカスタムの固有の識別子のプロパティーを指定して、特定のコンタクトレコードを一括で取得するには、crm/v3/objects/contacts/batch/readに対してPOSTリクエストを送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。
一括読み取りエンドポイントの場合は、任意指定のidPropertyパラメーターを使用し、emailまたはカスタムの固有の識別子のプロパティーを指定して、コンタクトレコードを取得することもできます。既定で、リクエストのid値はレコードID（hs_object_id）を表すので、レコードIDを使用して取得する場合はidPropertyパラメーターは不要です。emailまたはカスタムの固有の値のプロパティーを使用してコンタクトレコードを取得する場合は、idPropertyパラメーターを含める必要があります。

例えば、レコードIDの値に基づいてコンタクトを一括で取得する場合のリクエストは、次のようになります（現在の値のみ、または現在と過去の値）。

///Example request body with record ID (current values) { "properties": [ "email", "lifecyclestage", "jobtitle" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }
///Example request body with record ID (current and historical values) { "propertiesWithHistory": [ "lifecyclestage", "hs_lead_status" ], "inputs": [ { "id": "1234567" }, { "id": "987456" } ] }

Eメールアドレスまたはカスタムの固有の識別子のプロパティー（例：貴社に固有のお客様ID番号）に基づいてコンタクトレコードを取得する場合のリクエストは、次のようになります。

///Example request body with email { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "email", "inputs": [ { "id": "lgilmore@thedragonfly.com" }, { "id": "sstjames@thedragonfly.com" } ] }
///Example request body with a unique value property { "properties": [ "email", "lifecyclestage", "jobtitle" ], "idProperty": "internalcustomerid", "inputs": [ { "id": "12345" }, { "id": "67891" } ] }

コンタクトレコードを更新する

コンタクトレコードを個別に、または一括で更新できます。既存のコンタクトレコードの場合、EメールとレコードIDはどちらも一意の値なので、APIでidまたはemailを指定することで、コンタクトレコードを更新できます。

コンタクトIDを基準に個々のコンタクトレコードを更新するには、PATCHリクエストを/crm/v3/objects/contacts/{contactId}に送信します。リクエストには、更新するデータを含めます。

既存のコンタクトを他のレコードまたはアクティビティーに関連付ける

コンタクトを他のCRMレコードまたはアクティビティーに関連付けるには、PUTリクエストを/crm/v3/objects/contacts/{contactId}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

associationTypeId値を取得するには、この既定値リストを参照するか、GETリクエストを/crm/v4/associations/{fromObjectType}/{toObjectType}/labelsに送信します。 

詳しくは関連付けAPIをご参照ください。

関連付けを削除する

コンタクトと他のレコードまたはアクティビティーの関連付けを削除するには、DELETEリクエストを/crm/v3/objects/contacts/{contactID}/associations/{toObjectType}/{toObjectId}/{associationTypeId}に送信します。

コンタクトレコードでアクティビティーをピン留めする

You can pin an activity on a contact record by including the hs_pinned_engagement_id field in your request. In the field, include the id of the activity to pin, which can be retrieved via the engagements APIs. You can pin one activity per record, and the activity must already be associated with the contact prior to pinning.

To set or update a contact's pinned activity, your request could look like:

///Example request body PATCH /crm/v3/objects/contacts/{contactId} { "properties": { "hs_pinned_engagement_id": 123456789 } }

You can also create a contact, associate it with an existing activity, and pin the activity in the same request. For example:

///Example request body POST /crm/v3/objects/contacts { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "hs_pinned_engagement_id": 123456789 }, "associations": [ { "to": { "id": 123456789 }, "types": [ { "associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 201 }] }] }

Delete contacts

コンタクトレコードを個別に、または一括で削除できます。削除したコンタクトレコードは、HubSpot内のごみ箱に追加されます。そのため、必要に応じて後でHubSpot内でコンタクトレコードを復元できます。

IDを基準に個々のコンタクトレコードを削除するには、DELETEリクエストを/crm/v3/objects/contacts/{contactId}に送信します。

コンタクトレコードを一括で削除する方法については、この記事の上部にある［エンドポイント］タブをクリックしてください。

制限

Batch operations for creating, updating, and archiving are limited to batches of 100. There are also limits for contacts and form submissions.

参考になりましたか？
こちらのフォームではドキュメントに関するご意見をご提供ください。HubSpotがご提供しているヘルプはこちらでご確認ください。