Consent | REST API 開発者ガイド

Consent API は、レコードに参照関係がある場合、取引先オブジェクト、連絡先種別に関する同意オブジェクト、データ使用目的オブジェクト、個人オブジェクト、リードオブジェクト、個人取引先オブジェクト、ユーザオブジェクトに保存された同意設定を集計します。Consent API は、メールアドレス項目がプラットフォームの暗号化によって保護されているレコードを見つけることはできません。

API は、メールやトラックなどの単一のアクションに基づいて同意の詳細情報を返します。API バージョン 45.0 からは、複数アクションのエンドポイントによって、1 回の API コールで複数のアクションを要求できます。

構文

URI

/services/data/vXX.0/consent/action/action?ids=list_of_Ids

/services/data/vXX.0/consent/multiaction?actions=list_of_actions&ids=list_of_Ids (API バージョン 45.0 以降で使用可能)

適用開始バージョン

44.0

形式

JSON

HTTP メソッド

GET

認証

Authorization: Bearer token

リクエストボディ

なし

要求パラメータ

パラメータ	説明
actions	提案されたアクションのカンマ区切りリスト。この必須パラメータは、複数アクションのエンドポイントにのみ適用されます。このパラメータは API バージョン 45.0 以降で使用できます。これが使用されている場合、action は使用できません。
aggregatedConsent	省略可能: true または false。`aggregatedConsent` は、`aggregatedConsent=true` と同じです。true の場合、各 ID の結果ではなく、進むか否かを示す結果が 1 つ返されます。リスト内のいずれかの ID で false が返されると、集計された結果は false になります。
datetime	省略可能。同意が確定された際のタイムスタンプ。値は UTC タイムゾーンに変換され、ISO 8601 形式で指定される必要があります。指定されていない場合、デフォルトの現在の日付と時刻に設定されます。
ids	必須。ID のカンマ区切りのリスト。ID には、レコード ID か、レコードに記載されたメールアドレスを使用できます。
purpose	省略可能。顧客に連絡する理由。
verbose	省略可能: true または false。`verbose` は `verbose=true` と同じです。verbose レスポンスは、verbose 以外のレスポンスより時間がかかります。verbose レスポンスの例を参照してください。

アクション

有効な値は、次のとおりです。

email
fax
geotrack
mailing
phone
portability
process
profile
shouldForget
social
solicit
storePiiElsewhere
track
web

action が使用されている場合、actions は使用できません。

action として email を選択すると、同じメールアドレスを含むレコードの同意のみが集計されます。URI で指定されたレコード ID が異なるメールアドレスを含むレコードに関連付けられている場合、その関連レコードの同意設定は API レスポンスに含まれません。

メモ

例

単純な URI 構造

1/services/data/v44.0/consent/action/track?ids=003xx000004TxyY,00Qxx00000syyO,003zz000004zzZ

複数アクションの URI 構造

1/services/data/v44.0/consent/multiaction?actions=track,geotrack,email&ids=003xx000008TiyY,00Qxx00000skwO,dek65@tf7h.com

ID としてのメールアドレス、指定された目的と期間、および verbose レスポンス

1/services/data/v46.0/consent/action/email?ids=j0t5t5b2@tkbxp5ia.com,4quxlswo@23wj7pwh.com&datetime=2018-12-12T00:00:00Z&purpose=billing&verbose=true

応答

1{
2  "j0t5t5b2@tkbxp5ia.com" : {
3    "result" : "Success",
4    "proceed" : {
5      "email" : "true"
6      "emailResult" : "Success"
7    },
8    "explanation" : [ {
9      "objectConsulted" : "ContactTypePointConsent",
10      "status" : "opt_in",
11      "purpose" : "billing",
12      "recordId" : "003xx000004TxyY",
13      "value" : "true"
14    },{
15      "objectConsulted" : "Contact",
16      "field" : "HasOptedOutOfTracking",
17      "recordId" : "1",
18      "value" : "true"
19    }]
20  },
21  "4quxlswo@23wj7pwh.com" : {
22    "result" : "Success",
23    "proceed" : {
24      "email" : "false"
25      "emailResult" : "Success"
26    },
27    "explanation" : [ {
28      "objectConsulted" : "Contact",
29      "field" : "HasOptedOutOfEmail",
30      "recordId" : "00Qxx00000skwO",
31      "value" : "true"
32    }  ]
33  }
34}

セキュリティ

Consent API をコールするには、「すべてのデータの参照」または「プライバシーデータへのユーザのアクセスを許可」ユーザ権限を持っている必要があります。権限を必須にすることで、システム管理者は明示的権限を付与できます。これは、この API が、ユーザが通常アクセスするレコードだけでなく、レコード間のリンクや同意フラグの値など、組織全体の同意データにアクセスするためです。

使用方法

次の表に、API レスポンスの決定方法を示します。参照される項目に競合する同意の設定があると、レスポンスは権限が最小限の設定を返します。たとえば、Contact.HasOptedOutOfEmail が false であるが、Lead.HasOptedOutOfEmail が true の場合、ユーザへのメール送信を継続できないことを示すレスポンスが返されます。

action として email を選択すると、同じメールアドレスを含むレコードの同意のみが集計されます。URI で指定されたレコード ID が異なるメールアドレスを含むレコードに関連付けられている場合、その関連レコードの同意設定は API レスポンスに含まれません。

API で複数のレコードの同意設定が比較されるとき、変換されたリードの設定は含まれません。

メモ

アクション	参照する項目	API レスポンス	レスポンスのスキーマ
email	Contact.HasOptedOutOfEmail ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name Lead.HasOptedOutOfEmail PersonAccount.HasOptedOutOfEmail	ContactPointTypeConsent で指定する場合は、時間範囲内: 参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する連絡先オブジェクト、連絡先種別に関する同意オブジェクト、リードオブジェクト、個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "emailResult" : "<Success/errormessage>", email : “<true/false>” } } }
fax	Contact.HasOptedOutOfFax DataUsePurpose.Name Lead.HasOptedOutOfFax PersonAccount.HasOptedOutOfFax	参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する取引先責任者、リード、または個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "faxResult" : "<Success/errormessage>", fax : "<true/false>" } } }
geotrack	DataUsePurpose.Name Individual.HasOptedOutGeoTracking	参照される項目値が 0 の場合、TRUE を返します。参照される項目値が 1 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "geotrackResult" : "<Success/errormessage>", "geotrack" : "<true/false>" } } }
mailing	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	ContactPointTypeConsent で指定する場合は、時間範囲内: 参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する連絡先オブジェクト、連絡先種別に関する同意オブジェクト、リードオブジェクト、個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "mailingResult" : "<Success/errormessage>", "mailing" : "<true/false>" } } }
phone	Contact.DoNotCall ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name Lead.DoNotCall PersonAccount.DoNotCall	ContactPointTypeConsent で指定する場合は、時間範囲内: 参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する連絡先オブジェクト、連絡先種別に関する同意オブジェクト、リードオブジェクト、個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "phoneResult" : "<Success/errormessage>", "phone" : "<true/false>" } } }
portability	DataUsePurpose.Name Individual.SendIndividualData	参照される項目値が 1 の場合、TRUE を返します。参照される項目値が 0 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "portabilityResult" : "<Success/errormessage>", "portability" : "<true/false>" } } }
process	DataUsePurpose.Name Individual.HasOptedOutProcessing	参照される項目値が 0 の場合、TRUE を返します。参照される項目値が 1 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "processResult" : "<Success/errormessage>", "process" : "<true/false>" } } }
profile	DataUsePurpose.Name Individual.HasOptedOutProfiling	参照される項目値が 0 の場合、TRUE を返します。参照される項目値が 1 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "profileResult" : "<Success/errormessage>", "profile" : "<true/false>" } } }
shouldForget	DataUsePurpose.Name Individual.ShouldForget	参照される項目値が 1 の場合、TRUE を返します。参照される項目値が 0 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "shouldForgetResult" : "<Success/errormessage>", "shouldForget" : "<true/false>" } } }
social	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	ContactPointTypeConsent で指定する場合は、時間範囲内: 参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する連絡先オブジェクト、連絡先種別に関する同意オブジェクト、リードオブジェクト、個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "socialResult" : "<Success/errormessage>", "social" : "<true/false>" } } }
solicit	DataUsePurpose.Name Individual.HasOptedOutSolicit	参照される項目値が 0 の場合、TRUE を返します。参照される項目値が 1 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "solicitResult" : "<Success/errormessage>", "solicit" : "<true/false>" } } }
storePIIElsewhere	DataUsePurpose.Name Individual.CanStorePiiElsewhere	参照される項目値が 1 の場合、TRUE を返します。参照される項目値が 0 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "storePIIElsewhereResult" : "<Success/errormessage>", "storePIIElsewhere" : "<true/false>" } } }
track	DataUsePurpose.Name Individual.HasOptedOutTracking	参照される項目値が 0 の場合、TRUE を返します。参照される項目値が 1 の場合、または関連する個人オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "trackResult" : "<Success/errormessage>", "track" : "<true/false>" } } }
web	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	ContactPointTypeConsent で指定する場合は、時間範囲内: 参照される項目値がすべて 0 の場合、TRUE を返します。参照される項目値のいずれかが 1 の場合、または関連する連絡先オブジェクト、連絡先種別に関する同意オブジェクト、リードオブジェクト、個人取引先オブジェクトが存在しない場合、FALSE を返します。	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "webResult" : "<Success/errormessage>", "web" : "<true/false>" } } }