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 is the same as the Property ID and can be found on the Properties page inline with the property name.
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.
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 use a third party service like Postman to retrieve an end-user's consent status.
Use the POST method and provide the correct API endpoint url and values for site id and consentUUID to retrieve an end-user's consent status.
It is important that your organization provides the tcString to which the end-user's consent profile will be updated to. This must be sent in the body of the POST request in JSON format:
{"euconsent":"CPOA6HgPOA6HgFZABCDEBwCgAP_AAEwAAAYgIDpb_T7VbWFCWf59fvsgOYxXVMCeA-QCAASAJ2ABgAKQcDwCkmAaNESgBgACIQAAoTJBIAIEDAEECUAA4AAEAAGgAAAEhAAIIAAAgBEAAAIYAAoCAIAAAACIwAAQEAAAm1gYA-bmGEBAhAAAYAgQgAAAAAIAAgAAAAAIAAAAAAAAAAgeOhGZIlVNQUDB6E08gAAIgBBUgBgAIAAAAIAiYACAABBgDAAAQBoAQIAAAAIgAACAEAEAAAAAAAQAQAAgAAQAAKAAAACAAAgAAACAEQAAABAACAIAgAAAAABAAAAAAACAEBAAAgIYAAAAAAAAAASAAAEAAgAAAAAAAAgJjIA4AQwAmACZAGoAPwAjgC8xoAEAFQwAEAWIA6oiAUAFYALYAhgBqAD8AOqAi8BOwCkQGTiAAIAJAoCMAAIABgAFAASABFACcAKAAVAAsAB2AEIAI4AUAApABXAC2AIsAaIA1ABxgEIgJMAk4BNACdgFZAK6AX4A_YB_QElgJaAU2AsQBfwDGQG1hoBwAVAArQBbAFwAQwA1AB-AEFANkAdUBF4CdgFIgMYAZOGABAHUAX0KgEgBDACYAFwATIA1AB-AEcAU2AvMWABABUKABgEFAOqAvodA2AAWABUADIAHAAQAAyABoADwAH0AQwBFACYAE-AKoArABYgC2ALoAXwAxABvADmAH4AQwAiIBLAEwAKMAUoAsQBhgDRAGoAPaAfgB-gEWAI4ASkAsQBcwC6gGKANwAcQA6gB6AENgIvATsAocBeYDBgGJAMYAZOAywBqoDxxwBaABwAHgAXABIADkAH4AzQCCwEHAQgAiIBeoDAAMCAZkA14B0gDqgHkASsArsBfQDIQGTANoIQFgAFgAZACGAEwAKoAXAAvgBiADeALEAagA_ACOAEpALmAYoA6gB6AGJAMnAaqA8cgAHAB-AQUAsQBgADMgHVAX0SgNgALAAyABwAHgARAAmQBUAFUALgAXwAxABtAEMAIgAUYApQBqgD8AI4AScAuoBigDcAHUAReAvMBk4DLCQAkABwAFwAcgDUAMyAa8A6oCVgF9FIFIACwAKgAZAA4ACAAGQANAAeQBDAEUAJgATwApQBUAFUALAAXwAxABzAD8AIYARAAmQBRgClAFiANEAasA_AD9AIsARwAlIBcwDFAG4APQAi8BOwChwF5gMYAZOA8coATAAuACQAHIAPwArABtAGoAScAnYBYgC6gGAANeAdUA8gCuwF9AMmAcEAA.YAAAAAAAAAAA"}
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 |