Consents

A consent is something that an end-user of Engage has agreed to (or not agreed to) concerning their data or their account. Proper handling of consents is very important from a legal perspective. They turn up in the POS or, in the case of an e-com, on the website and are essentially requests from the retailer that the end-user can choose to allow or deny.

An example would be: "Do you agree to receive our newsletter?" For each contact, the consent can be in one of three states:

Yes (aka True) - The contact has agreed to receive the newsletter
No (aka False) - The contact does not want to receive the newsletter
Not set - The contact has not yet given their answer

Important

Once its value has been set, a consent can only have the value "Yes" or "No". It can never again revert to “Not set”. This is by design. The consent can, however, be changed between "Yes" and "No".

Setting up a consent

A consent is set up in the Engage back-end by your Voyado team. Each consent definition contains four text fields:

Name: A name for this consent (defaults to the unique string chosen when the consent is created).

Displaytext: The description of the consent that is displayed in the POS or e-com.

Linktext: The text that, when clicked on, leads to the full terms and conditions.

Conditiontext: The full terms and conditions, in HTML format.

The three data fields can contain localised versions of their texts. See image:

The Conditiontext fields have been truncated for this example. Normally, they would be a whole page of HTML formatted text. Since Engage has no versioning of fields, this text is often stored at an external URL, which is managed by the customer. Your Voyado team will help you with setting this up.

All texts in these fields can be localised, as seen in the image, following the standard for language culture names (sv-SE, en-GB, fr-FR and so on).

Seeing all consents for a tenant

There can be more than one consent in use. To see the all consents for a tenant, this endpoint is used:

GET /api/v2/consents

This returns a JSON array with all the consents for that tenant (or an empty array if there are no consents). Note that this holds no information about how individual contacts have responded to the consents.

[
   {
      "name":"Consent for Prescription Purchase",
      "id":"consentRX",
      "metaData":{
         "displayText":{
            "en-GB":"I consent to Rx purchases."
         },
         "linkText":{
            "en-GB":"Read the terms here."
         },
         "conditionText":{
            "en-GB":"The terms as a HTML block."
         }
      }
   },
   {
      "name":"Consent for Membership Terms",
      "id":"consentMemberTerms",
      "metaData":{
         "displayText":{
            "en-GB":"Yes, I consent."
         },
         "linkText":{},
         "conditionText":{}
      }
   }
]

Getting a contact's consent states

By fetching a contact's data using the v2/contactoverview endpoint, you can see what consents exist for this contact, and what their state is.

{
  "firstName": "Example",
  "email": "example@example.com",
  "countryCode": "SE",
  "contactType": "ExampleContactType",
  "preferences": {
    "acceptsEmail": true,
    "acceptsPostal": true,
    "acceptsSms": true
  },
  ...
  "consents": [{
      "id": "consentMemberTerms",
      "value": true,
      "date": "2022-01-01T00:00:00+0100",
      "source": "ECOM",
      "comment": "Approved member terms at checkout"
   }]
}

Note that only consents with a value or "true" or "false" will be shown in this response. So if a consent is not set, it will not show up here. You can, however, fetch all the consents through v2/consents and combine that with the consent data returned for an individual contact. In this way, all consents can be shown for a contact (for example, in the POS) even if their value is not set.

Tip

By combining all the consents for a tenant from v2/consents with a specific contact's consents fetched from v2/contactoverview, you can build up a complete picture of the consents for that specific contact, including the ones not set.

Giving or revoking a consent

Setting the state of a consent for an individual contact is done in the same way as for any contact update:

POST /api/v2/contacts/{contactId}

In the body of the update request, add the consent like this:

{
   "consents":[{ 
         "id": "consentMemberTerms", 
         "value": true, 
         "comment": "Some comment here", 
         "source": "POS" 
     }]
}

This would set the state of the "consentMemberTerms" consent to true (or Yes).

In this section: