Consent

Consent API aggregates consent settings across the Contact, 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&verbose=true_or_false&aggregatedConsent=true_or_false

/services/data/vXX.0/consent/multiaction?actions=list_of_actions&ids=list_of_Ids&verbose=true_or_false&aggregatedConsent=true_or_false (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.
ids	Required. Comma-separated list of IDs. The ID can be the record ID or the email address listed on the record.
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
• phone
• portability
• process
• profile
• shouldForget
• solicit
• storePiiElsewhere
• track

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, and a verbose response

1/services/data/v44.0/consent/action/email?ids=j0t5t5b2@tkbxp5ia.com,4quxlswo@23wj7pwh.com&verbose=true

Response

1{
2  "j0t5t5b2@tkbxp5ia.com" : {
3    "proceed" : {
4      "emailResult" : "Success",
5       "email" : "false"
6    },
7    "explanation" : [ {
8      "objectConsulted" : "Contact",
9      "field" : "HasOptedOutOfEmail",
10      "recordId" : "003xx000004TxyY",
11      "value" : "true"
12    } ]
13  },
14  "4quxlswo@23wj7pwh.com" : {
15    "proceed" : {
16      "emailResult" : "Success",
17      "email" : "true"
18    },
19    "explanation" : [ {
20      "objectConsulted" : "Contact",
21      "field" : "HasOptedOutOfEmail",
22      "recordId" : "003xx000004TxyZ",
23      "value" : "false"
24    } ]
25  }
26}

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.

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.