コンタクトレコードには、個人に関する情報が保存されます。コンタクトエンドポイントを使用することにより、コンタクトデータを管理したり、HubSpotと他のシステムとの間で同期したりできます。
POST
リクエストを/crm/v3/objects/contacts
に送信します。
リクエスト内のプロパティーオブジェクトにコンタクトデータを含めます。また、関連付けオブジェクトを追加して、新しいコンタクトを既存のレコード(会社、取引など)やアクティビティー(ミーティング、メモなど)に関連付けることもできます。
email
、firstname
、またはlastname
プロパティーのうち、少なくとも1つをリクエストに含める必要があります。Eメールアドレスはコンタクトを一意に識別する主要なIDであるため、HubSpotでコンタクトが重複しないようにするために、常にemail
を含めることを推奨します。
利用可能な全てのプロパティーを確認するには、GET
リクエストを/crm/v3/properties/contacts
に送信することで、アカウントのコンタクトプロパティーのリストを取得できます。詳しくはプロパティーAPIをご参照ください。
lifecyclestage
を含める場合、値はライフサイクルステージの内部名を参照する必要があります。デフォルトのステージの内部名はテキスト値であり、ステージのラベル(subscriber
やmarketingqualifiedlead
など)を編集しても変更されません。カスタムステージの内部名は数値です。ステージの内部IDは、ライフサイクルステージ設定か、API経由でライフサイクルステージプロパティーを取得することで確認できます。パラメーター | 説明 |
---|---|
to | コンタクトに関連付けるレコードまたはアクティビティー。一意のid 値で指定します。 |
types | コンタクトとレコードまたはアクティビティー間の関連付けのタイプであるassociationCategory とassociationTypeId を含めます。デフォルトの関連付けタイプIDはこちらのページに記載されています。または、関連付けAPIを使用して、カスタム関連付けタイプ(ラベル)の値を取得することもできます。 |
GET
リクエストを/crm/v3/objects/contacts/{contactId} or
または/crm/v3/objects/contacts/{email}?idProperty=email
に送信します。GET
リクエストを/crm/v3/objects/contacts
に送信します。パラメーター | 説明 |
---|---|
properties | レスポンスで返されるプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
propertiesWithHistory | レスポンスで返される現在および過去のプロパティーのカンマ区切りリスト。リクエスト対象のコンタクトレコードで、指定したプロパティーに値が設定されていない場合、そのプロパティーはレスポンスに含まれません。 |
associations | 関連付けられたIDを取得する対象のオブジェクトのカンマ区切りリスト。存在しない関連付けを指定した場合、その関連付けはレスポンスで返されません。詳しくは関連付けAPIをご参照ください。 |
POST
リクエストをcrm/v3/objects/contacts/batch/read
に送信します。このバッチエンドポイントは関連付けを取得できません。関連付けAPIを使用してバッチが関連付けを読み取る方法について説明します。idProperty
パラメーターを使用し、email
またはカスタムの固有の識別子のプロパティーを指定して、コンタクトを取得することもできます。デフォルトで、リクエストのid
値はレコードID(hs_object_id
)を参照するため、レコードIDを使って取得するときにはidProperty
パラメーターは不要です。email
またはカスタムの固有の値のプロパティーを使用してコンタクトを取得する場合は、idProperty
パラメーターを含める必要があります。
例えば、レコードIDの値に基づいてコンタクトを一括で取得する場合のリクエストは、次のようになります(現在の値のみ、または現在と過去の値)。
Eメールアドレスまたはカスタムの固有の識別子のプロパティー(例:自社に固有の顧客ID番号)に基づいてコンタクトレコードを取得する場合のリクエストは、次のようになります。
id
)またはコンタクトのEメールアドレス(email
)を使用します。
PATCH
リクエストを/crm/v3/objects/contacts/{contactId}
に送信し、更新対象のデータを含めます。PATCH
リクエストを/crm/v3/objects/contacts/{email}?idProperty=email
に送信し、更新対象のデータを含めます。id
)を使用できます。複数のコンタクトを更新するには、POST
リクエストを/crm/v3/objects/contacts/batch/update
に送信します。リクエスト本文に、各コンタクトのレコードIDをid
として含め、更新対象のプロパティーを含めます。
以下に例を示します。
email
またはカスタムの固有IDプロパティーを使用できます。リクエストに従って、コンタクトがすでに存在する場合は更新され、コンタクトが存在しない場合は作成されます。
コンタクトを一括更新するには、POST
リクエストを/crm/v3/objects/contacts/batch/upsert
に送信します。リクエスト本文にidProperty
パラメーターを含め、email
またはカスタムの固有IDプロパティーのどちらを使用しているかを識別します。そのプロパティーの値をid
として含め、設定または更新する他のプロパティーを追加します。
email
をコンタクトのidProperty
として使用する場合、部分的なアップサート(更新または挿入)はサポートされません。部分的なアップサートを実行するには、代わりにカスタムの固有IDプロパティーをidProperty
として使用します。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つのアクティビティーをピン留めすることができ、そのアクティビティーはピン留めする前に既にコンタクトに関連付けられている必要があります。
コンタクトのピン留めされたアクティビティーを設定または更新するリクエストは、次のようになります。
DELETE
リクエストを/crm/v3/objects/contacts/{contactId}
に送信します。
コンタクトを一括で削除する方法については、こちらの資料をご確認ください。
properties
パラメーターにemail
とhs_additional_emails
のプロパティーを含めます。コンタクトのプライマリーEメールアドレスはemail
フィールドに表示され、追加のEメールアドレスはhs_additional_emails
フィールドに表示されます。