コンタクト

概要エンドポイント

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

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

コンタクトを作成する

新しいコンタクトを作成するには、POSTリクエストを/crm/v3/objects/contactsに送信します。リクエスト内のpropertiesオブジェクトにコンタクトデータを含めます。

Please note: you cannot create a contact and associate it with a record or activity in the same request. To associate your contact with other records or activities, create the contact, then update the contact or create an association via the associations API.

プロパティー

コンタクトの詳細は、コンタクトプロパティーに保存されます。HubSpotの既定のコンタクトプロパティーがありますが、カスタム コンタクト プロパティーを作成することもできます。

新しいコンタクトを作成する際は、email、firstname、lastnameプロパティーのうち、少なくとも1つをリクエストに含める必要があります。Eメールアドレスはコンタクトを一意に識別する主要なIDであるため、HubSpotでコンタクトが重複しないようにするために、常にemailを含めることを推奨します。

利用可能な全てのプロパティーを確認するには、GETリクエストを/crm/v3/properties/contactsに送信して、アカウントのコンタクトプロパティーのリストを取得します。詳しくはプロパティーAPIをご参照ください。

Please note: if you've included lifecyclestage in your request, values must refer to the lifecycle stage's internal name. The internal names of default stages are text values, and do not change even if you edit the stage's label(e.g., subscriber or marketingqualifiedlead). The internal names of custom stagesare numeric values. You can find a stage's internal ID in your lifecycle stage settings,or by retrieving the lifecycle stage property via API.

例えば、新しいコンタクトを作成する場合、リクエストの内容は次のようになります。

///Example request body { "properties": { "email": "example@hubspot.com", "firstname": "Jane", "lastname": "Doe", "phone": "(555) 555-5555", "company": "HubSpot", "website": "hubspot.com", "lifecyclestage": "marketingqualifiedlead" } }

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

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

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

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

Use this table to describe parameters / fields
ParameterDescription
properties

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

associations

関連付けられているIDが取得されるオブジェクトの、カンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。

例えば、コンタクトとそのEメールアドレスおよび関連会社を取得する場合、リクエストのURLは、https://api.hubspot.com/crm/v3/objects/contacts?properties=email&associations=companiesのようになります。

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

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

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

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

Please note: the idProperty query parameter doesn't appear on the Endpoints tab due to technical limitations, but it can be used for contacts exclusively with email. To use an email address as the unique identifier, set the idProperty as email and enter the email address in place of the contact ID. This should be set as a query parameter rather than added to the request body.

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

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

To retrieve the associationTypeId value, make a GET request to /crm/v4/associations/{fromObjectType}/{toObjectType}/labels.

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

関連付けを削除する

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

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がご提供しているヘルプはこちらでご確認ください。