Consent | REST API Developer Guide | Salesforce Developers

Consent API aggregates consent settings across the Contact, Contact Point Type Consent, Data Use Purpose, Individual, Lead, Person Account, and User objects when the records have a lookup relationship. The Consent API can't locate records in which the email address field is protected by Platform Encryption.

The API returns consent details based on a single action, like email or track, or—starting with API version 45.0—the multiaction endpoint allows you to request multiple actions in a single API call.

Syntax

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 (Available in API version 45.0 and later.)

Available since release

44.0

Formats

JSON

HTTP methods

GET

Authentication

Authorization: Bearer token

Request body

None

Request parameters

Parameter	Description
actions	Comma-separated list of proposed actions. This required parameter applies only to the multiaction endpoint. This parameter is available in API version 45.0 and later. If this is used, action cannot be used.
aggregatedConsent	Optional: true or false. `aggregatedConsent` is the same as `aggregatedConsent=true`. If true, one result is returned indicating whether to proceed or not, rather than a result for each ID. If any ID in the list returns false, the aggregated result is false.
datetime	Optional. The timestamp for which consent is determined. The value is converted to the UTC timezone and must be specified in ISO 8601 format. If not specified, defaults to the current date and time.
ids	Required. Comma-separated list of IDs. The ID can be the record ID or the email address listed on the record.
purpose	Optional. The reason for contacting a customer.
verbose	Optional: true or false. `verbose` is the same as `verbose=true`. Verbose responses are slower than non-verbose responses. See the examples for a verbose response.

Action

Allowed values are:

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

If action is used, actions cannot be used.

When you select email as the action, the API only aggregates consent for records that contain the same email address. If the record ID specified in the URI is associated with a record that contains a different email address, the consent settings of the associated record aren’t included in the API response.

Note

Examples

Simple URI structure

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

Multiaction URI structure

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

Email addresses as IDs, specified purpose and timespan, and a verbose response

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

Response

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}

Security

To call Consent API, you must have either the View All Data or the Allow User Access to Privacy Data user permission. Requiring a perm ensures that the System Administrator gives explicit permission. This API accesses org-wide consent data, such as links between records and the value of consent flags, not just records to which the user ordinarily has access.

Usage

The following table shows how the API responses are determined. If the consulted fields find conflicting consent preferences, the response returns the least permissive preference. For example, if Contact.HasOptedOutOfEmail is false, but Lead.HasOptedOutOfEmail is true, the response indicates that you can’t proceed with emailing the user.

When you select email as the action, the API only aggregates consent for records that contain the same email address. If the record ID specified in the URI is associated with a record that contains a different email address, the consent settings of the associated record aren’t included in the API response.

When the API compares consent settings across records, it doesn’t incorporate settings from converted leads.

Note

Action	Fields Consulted	API Response	Response Schema
email	Contact.HasOptedOutOfEmail ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name Lead.HasOptedOutOfEmail PersonAccount.HasOptedOutOfEmail	Within the time range if specified in ContactPointTypeConsent: Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Contact Point Type Consent, Lead, or Person Account object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "emailResult" : "<Success/errormessage>", email : “<true/false>” } } }
fax	Contact.HasOptedOutOfFax DataUsePurpose.Name Lead.HasOptedOutOfFax PersonAccount.HasOptedOutOfFax	Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Lead, or Person Account object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "faxResult" : "<Success/errormessage>", fax : "<true/false>" } } }
geotrack	DataUsePurpose.Name Individual.HasOptedOutGeoTracking	Returns TRUE if the consulted field value is 0. Returns FALSE if the consulted field value is 1 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "geotrackResult" : "<Success/errormessage>", "geotrack" : "<true/false>" } } }
mailing	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	Within the time range if specified in ContactPointTypeConsent: Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Contact Point Type Consent, Lead, or Person Account object exists.	{ "<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	Within the time range if specified in ContactPointTypeConsent: Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Contact Point Type Consent, Lead, or Person Account object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "phoneResult" : "<Success/errormessage>", "phone" : "<true/false>" } } }
portability	DataUsePurpose.Name Individual.SendIndividualData	Returns TRUE if the consulted field value is 1. Returns FALSE if the consulted field value is 0 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "portabilityResult" : "<Success/errormessage>", "portability" : "<true/false>" } } }
process	DataUsePurpose.Name Individual.HasOptedOutProcessing	Returns TRUE if the consulted field value is 0. Returns FALSE if the consulted field value is 1 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "processResult" : "<Success/errormessage>", "process" : "<true/false>" } } }
profile	DataUsePurpose.Name Individual.HasOptedOutProfiling	Returns TRUE if the consulted field value is 0. Returns FALSE if the consulted field value is 1 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "profileResult" : "<Success/errormessage>", "profile" : "<true/false>" } } }
shouldForget	DataUsePurpose.Name Individual.ShouldForget	Returns TRUE if the consulted field value is 1. Returns FALSE if the consulted field value is 0 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "shouldForgetResult" : "<Success/errormessage>", "shouldForget" : "<true/false>" } } }
social	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	Within the time range if specified in ContactPointTypeConsent: Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Contact Point Type Consent, Lead, or Person Account object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "socialResult" : "<Success/errormessage>", "social" : "<true/false>" } } }
solicit	DataUsePurpose.Name Individual.HasOptedOutSolicit	Returns TRUE if the consulted field value is 0. Returns FALSE if the consulted field value is 1 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "solicitResult" : "<Success/errormessage>", "solicit" : "<true/false>" } } }
storePIIElsewhere	DataUsePurpose.Name Individual.CanStorePiiElsewhere	Returns TRUE if the consulted field value is 1. Returns FALSE if the consulted field value is 0 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "storePIIElsewhereResult" : "<Success/errormessage>", "storePIIElsewhere" : "<true/false>" } } }
track	DataUsePurpose.Name Individual.HasOptedOutTracking	Returns TRUE if the consulted field value is 0. Returns FALSE if the consulted field value is 1 or if no related Individual object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "trackResult" : "<Success/errormessage>", "track" : "<true/false>" } } }
web	ContactPointTypeConsent.ContactPointType ContactPointTypeConsent.EffectiveFrom ContactPointTypeConsent.EffectiveTo ContactPointTypeConsent.PrivacyConsentStatus DataUsePurpose.Name	Within the time range if specified in ContactPointTypeConsent: Returns TRUE if all consulted field values are 0. Returns FALSE if any consulted field value is 1 or if no related Contact, Contact Point Type Consent, Lead, or Person Account object exists.	{ "<ID/Email>" : { "result" : "<Success/errormessage>", "proceed" : { "webResult" : "<Success/errormessage>", "web" : "<true/false>" } } }