Update end-user consent profile with Sourcepoint API

Sourcepoint offers an API access that allows your organization to merge an end-user's custom vendor consent profile with the information Sourcepoint has for IAB vendors taken from a TCString that is provided. This article provides a brief background and describes the API access requirements. Example code is provided to help your organization with their setup and the response from the API is explained.

  Note: Your organization will require their own CMP ID to use this API. Please contact your Sourcepoint Client Support team if you require more information.

This API was originally planned for the German consortium NetId to allow end-users to manage their consent data more easily in one place, instead of through the privacy managers of different publishers.

This API is not built exclusively for NetId. It is open to any identity provider that allows end-users to confirm or revoke vendor consent in one place. The Sourcepoint API endpoint receives the consentUUID and consent string. It merges the data found in the consent string with the Sourcepoint's consent data for IAB vendors then returns the new consent tcString as the response.


API endpoint & requirements

  Note: Sourcepoint offers another API service that allows your organization to retrieve an end-user's consent profile. For more information, click here.

The API endpoint to retrieve an end-user's consent information requires the siteID and consentUUID values.

The API endpoint is the following:

https://cdn.privacy-mgmt.com/consent/tcfv2/consent/v3/{__SITE_ID__}/tcstring?consentUUID={__CONSENT_UUID__}

This API endpoint has two placeholders that need to be replaced with the correct values:

  • A property's site id {__SITE_ID__}
  • The cookie consent UUID {__CONSENT_UUID__}

  Note: The site id value can be found by selecting a property from the Dialogue dashboard and navigating to the browser address bar. The site id value will be shown in the browser address bar.

site_id.png

The consentUUID value can be retrieved from the first-party cookie consentUUID.


Retrieve consent status

Your organization can call the API endpoint using a server-side script or a third-party service like Postman.

Server-side script (PHP example) Using Postman

Your organization could use a server side script using code similar to the following PHP example to retrieve an end-user's consent status. You will need to provide the correct values for site id and consentUUID in the script.

<?php
    
$site_id = YYYY;
$consent_uuid = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXX";
$api_endpoint = "https://cdn.privacy-mgmt.com/consent/tcfv2/consent/v3/".$site_id."/tcstring?consentUUID=".$consent_uuid;
$handle = curl_init($api_endpoint);
$fileHandle = fopen("netID_consent.json", "w");

/* If you encounter an 'SSL certificate problem: unable to get local issuer certificate' then enable the following two lines */
/* This is NOT recommended as a solution and should only be used as a quick and temporary fix */
//curl_setopt($handle, CURLOPT_SSL_VERIFYHOST, 0);
//curl_setopt($handle, CURLOPT_SSL_VERIFYPEER, 0); 

/* Increase the buffer size to accomodate long tcStrings */
curl_setopt($handle, CURLOPT_BUFFERSIZE, 84000); curl_setopt($handle, CURLOPT_CUSTOMREQUEST, "POST");

/* Insert the current consent string from the end-user here */
$tcstring = array("euconsent" => "XXXXXXXXXXXXXXXXXXXX_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXXX.XXXXX");
$json_string = json_encode($tcstring);

curl_setopt($handle, CURLOPT_POSTFIELDS, $json_string); curl_setopt($handle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($handle, CURLOPT_HTTPHEADER, array (
'Content-Type: application/json',
'Content-Length: ' . strlen($json_string))
); curl_setopt($handle, CURLOPT_FILE, $fileHandle); curl_exec($handle); curl_close($handle); fclose($fileHandle); ?>

The API response will return the new end-user consent profile if the update has been successful.


Your organization can also confirm the end-user's updated consent profile through the browser console. First reload the website then in the browser console window use the TCFv2 API command:

__tcfapi('getTCData', 2, function(tcdata,success) {    console.log("retrieving TCDATA:", tcdata)    });

For more information on this command and more, click here.


The API JSON response

The API will return the following response if the request to retrieve an end-user's consent status history has been successful.

//Example JSON response
{
    "categories": [
        "5e8b11c3ebdb0627ecca27ab",
        "5e8b11c3ebdb0627ecca279c",
        "5e8b11c3ebdb0627ecca279f",
        "5e8b11c3ebdb0627ecca27a0",
        "5e8b11c3ebdb0627ecca279d",
        "5e8b11c3ebdb0627ecca279b",
        "5e8b11c3ebdb0627ecca279e",
        "5e8b11c3ebdb0627ecca27a1",
        "5e8b11c3ebdb0627ecca27a2",
        "5e8b11c3ebdb0627ecca27a3"
    ],
    "legIntCategories": [
        "5e8b11c3ebdb0627ecca279c",
"5e8b11c3ebdb0627ecca279d",
"5e8b11c3ebdb0627ecca279b" ], "vendors": [], "legIntVendors": [ "5e7792c8d8d48d7950873ff3", "5e7f6927b8e05c48537f6074", "5e7786abf443bb795772efee", "5e77890cd8d48d7950873ef7", "5e7793636fbbc471e4b62573", "5f21834b4e23d23c6c4ce0f3", "5f2a2b392b87b72624a333f2", "5f1b2fbeb8e05c306f2a1ed5" ], "_id": "61263285702648036d7d2d8c", "consentUUID": "d0640748-7cae-4d3e-8f72-494a15815923", "siteId": 6804, "vendorListId": "5e7790deb8e05c48537f6052", "rejectedAny": true, "fromNetId": true, "dateCreated": "2021-08-25T12:07:33.691Z", "__v": 0 }
Parameter Description
categories, legIntCategories The purpose ids given consent for the end-user returned by the API call. Also includes legitimate interest purposes.
vendors, legIntVendors Vendor ids given consent for the end-user returned by the API call. Also includes legitimate interest purposes.
_id The request id
consentUUID The consentUUID value
siteId The site id value
vendorListId The active Sourcepoint vendor list id
rejectedAny Set to true if any purpose has been rejected after the API call
fromNetID Is the consent profile from an end-user using the netID single sign-on
dateCreated The timestamp for the netID request
Was this article helpful?
0 out of 0 found this helpful