Ethyca Home

Consent via the API

Suggest Edits

Who This Document Is For

This document is suitable for teams configuring consent for:

  • web applications
  • mobile applications including advertising SDKs
  • bath and ETL pipelines

Introduction

Ethyca unifies and manages consent for all defined purposes of processing across your business for which consent may need to be gathered.

This means that end-users of your systems can manage their consent preferences and you can ensure that their consent is respected by both internal and 3rd party systems that process your users' data.

This article outlines how you can gather a user's consent and set this in Ethyca Consent via the API so that you can ensure correct consent preferences are set and enforced across all of your organizations' systems and data processes.

How Ethyca Consent Works

Once Ethyca's Privacy Center is fully configured, your users and customers can manage their consent preferences directly from your Privacy Center or, as shown in this article, via your web and mobile application UI, which can then submit consent to Ethyca via the API.

3840

As shown in the diagram above, you can set consent at any time to reflect the preferences of users consent status and ensure that their data is being managed appropriately.

When a user changes their consent for a processing activity, a record of this can be made by having the user manage this from the Privacy Center or by submitting a consent change via an API.

Getting Consent For Your Users

Ethyca provides an endpoint to get the current consent status for your users

GET Consent Request

curl --location --request GET '[BASE URL]/consent' \  
 --header 'Authorization: 0R6Z<API KEY ISSUED BY ETHYCA>LS/5ON'

To call the consent API, use your API Key as the Authorization header.

This will fetch the entire list of data subjects in your organization that have consented or objected to any Data Use Cases and their consent value.

GET Consent Response

[  
     {  
     "subjectIdentity":"[email protected]",  
     "processingActivityName":"Data Sales",  
     "consented":false,  
     "created": "2020-08-03T23:19:25",  
     "lastUpdated": "2020-08-03T23:19:25"  
     },  
     {  
     "subjectIdentity":"[email protected]",  
     "processingActivityName":"Data Sales",  
     "consented":false,  
     "created": "2020-08-04T13:25:36",  
     "lastUpdated": "2020-08-010T21:12:42"  
     },    
     {  
     "subjectIdentity":"[email protected]",  
     "processingActivityName":"Data Sales",  
     "consented":true,  
     "created": "2020-08-029T20:46:24",  
     "lastUpdated": "2020-08-20T22:56:19"  
     }  
    ]

The response object values correspond with each time the data subject entered a new consent value, where:

  • subjectIdentity: Is the identifier for the data subject. Today, this is the email address that the user has entered in your Privacy Center
  • processingActivityName: The name of the processing activity for which consent has been set. Processing Activity names are created and set from the Ethyca Control Panel by you.
  • consented: A boolean for the current status of the user related to this processing activity.

GET Consent Advanced Practices

Ethyca provides more advanced usage of the Consent API by providing parameters to filter consent data. You can essentially filter consent records via the processing activity (processingActivityName parameter), consented status (consented parameter), which will be true or false, and a user's email (email parameter).

Fetch Consent via a Subject's Email Address

To fetch an individual subject's consent records, you can send a url-encoded email parameter with your request like so:

curl --location -G '[BASE URL]/consent' \  
--data-urlencode '[email protected]' \  
--header 'Authorization: 0R6Z<API KEY ISSUED BY ETHYCA>LS/5ON'

Fetch Consent via Processing Activity and/or Consent Value

To fetch consent records via a processing activity, you can utilize the processingActivityName and consented parameters. In the example below, we will retrieve consent records from the myProcessingActivity processing activity where the consent is set to FALSE. 

curl --location -G '[BASE URL]/consent' \  
--data-urlencode 'processingActivityName=myProcessingActivity&consented=false' \  
--header 'Authorization: 0R6Z<API KEY ISSUED BY ETHYCA>LS/5ON'

In the example below, we will retrieve consent records from the myProcessingActivity processing activity where consent is set to TRUE and the user email is = [email protected]

curl --location -G '[BASE URL]/consent' \  
--data-urlencode 'processingActivityName=myProcessingActivity&consented=true&[email protected]' \  
--header 'Authorization: 0R6Z<API KEY ISSUED BY ETHYCA>LS/5ON'

Fetch Consent within a certain date range

To fetch consent records that were either created or updated in a certain time period, you can utilize the createdFrom, createdTo, lastUpdatedFrom, and lastUpdatedTo parameters. In the example below, we will fetch consent values for a specific subject that was created between 2020-12-08T17:28:23 and 2022-09-08T17:28:23 and updated between 2020-12-08T17:28 and 2023-09-08T17:28

curl --location --request GET 'http://localhost:8080/consent?email=johnsmirth%40example.com&createdFrom=2020-12-08T17:28:23&createdTo=2022-09-08T17:28:23&lastUpdatedFrom=2020-12-08T17:28:23&lastUpdatedTo=2023-09-08T17:28:23' \ 
--header 'Authorization: 0R6Z<API KEY ISSUED BY ETHYCA>LS/5ON'

Setting Consent For Your Users

Ethyca provides an endpoint for setting the consent status of your users programmatically.

POST Consent Request

curl --location --request POST '[BASE URL]/consent' \
--header 'accept: */*' \
--header 'Authorization: <your api key>' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "consented": false,
        "processingActivityName": "Test Consent",
        "email": "[email protected]",
        "domain": "privacy.example.com"
    },
    {
        "consented": true,
        "processingActivityName": "Test Consent",
        "email": "[email protected]",
        "domain": "privacy.example.com"
    }
]'

This will set a consent value of a subject for a specific Data Use Case. You may include one to many consent values for subjects in the API call. To call the consent API, use your API Key as the Authorization header. Below is an explanation of the parameters for this endpoint:

  • consented: A boolean for the current status of the user related to this processing activity.
  • processingActivityName: The name of the Data Use Case (also known as "processing activity") for which consent is being applied to. Processing Activity names are created and set from the Ethyca Control Panel by you.
  • email: The email address for the data subject.
  • domain: The url domain of your privacy center. To obtain the privacy center domain, reach out to your DNS provider to identify your CNAME. Note: This is an optional parameter. However, if you do not include it in your API request, the subject may see some discrepancies when viewing their consent information in the Ethyca Privacy Center.

POST Consent Response

If the API call was successful, the response status code will be 200 and there is no response body.

Implementation Best Practices

  • Updating a subject's consent via the API with your API key does not require a verification code input from the subject. Keep this in mind during your usage of the Consent API.
  • Because the Consent API allows you to update subject consent, ensure that you are storing your API key in a way that adheres to security best practices.
  • To obtain an API key, please reach out to you Ethyca Customer Success Manager or contact [email protected]

If Your Business Manages Pixels

Please visit each of the below support articles if your business manages pixels in any additional locations:

Support

Please contact [email protected] if you have any questions regarding implementation.

Updated over 1 year ago