The Preference Center APIs can be used to build out custom Preference Centers using the Multi Page template. The following steps outline how you can make use of the Preference Center schema to build out your custom Multi Page Preference Center.
- Complete the following in the OneTrust application
2. Create purposes, topics, and purpose preferences
3. Obtain the Preference Center GUID
4. Create OAuth 2.0 Credentials and generate a token - Retrieve the preference center root and page schema and the data subject's language and consent status
- Build your Preference Center UI
- Use the APIs to update consent preferences
Step 1: Complete the following in the OneTrust application
- Create purposes, topics, and purpose preferences
- Create a Preference Center using the Multi Page template
- Obtain the Preference Center GUID
- Create OAuth 2.0 Credentials and generate a token
Create purposes, topics, and purpose preferences
In the OneTrust application, first create purposes, topics, and purpose preferences to be configured within the Preference Center. For more information, see the following articles in myOneTrust.
Note: Alternatively, you can create purposes using the POST /v1/purposes endpoint.
You can also create purpose preferences using the POST /v1/custompreferences endpoint.
Create a Preference Center using the Multi Page template
On the Preference Centers screen, create a preference center using the Multi Page template. For more information, see
Creating a Multi Page Preference Center in myOneTrust.
Obtain the Preference Center GUID
Once you've created the Preference Center, the Preference Center Details screen will appear. You will then need to obtain the GUID of the Preference Center. You can find the GUID within the URL of the Preference Center.
Note: Alternatively, you can retrieve a list of all Preference Centers in the account using the GET /v2/preferencecenters endpoint. You can then find the Preference Center GUID for a specific Preference Center within the response.
Create OAuth 2.0 Credentials and generate a token
Create and manage API keys that utilize the OAuth 2.0 authorization framework using the Credentials screen in Global Settings. Once created, generate an access token. For more information, see Managing OAuth 2.0 Client Credentials.
Warning
These OneTrust APIs are meant to be used only on the backend servers, not on the frontend. On the frontend user interface (UI), the customer is responsible for handling authentication in order to display preferences using the data received from the OneTrust APIs. However, it's crucial not to use OneTrust API Keys or Client Credentials on the frontend to prevent users from gaining unauthorized access to the OneTrust APIs.
Step 2: Retrieve the preference center root and page schema and the data subject's language and consent status
In this step, you will use the GET /v2/preferencecenters/{preferencecenterid}/schema, GET /v2/preferencecenterpage/{preferencecenterpageid}/schema, and GET /v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoints. The responses you receive from these API calls will be used to build your Preference Center UI in step 3.
- Retrieve the preference center root schema
- Retrieve the required ID within the Pages attribute
- Retrieve the schema for each required page
- Retrieve the data subject's language and consent status
Retrieve the preference center root schema
The GET /v2/preferencecenters/{preferencecenterid}/schema endpoint can be used to retrieve the preference center root schema for a given Multi Page Preference Center GUID.
Note: The Unique identifier of the Preference Center is denoted as {preferencecenterId}.
Example Request:
GET https://trial.onetrust.com/api/consentmanager/v2/preferencecenters/370694df-20ac-4105-9a8b-327558e7e70f/schema
Example Response Body:
{
"pages": [{
"id": "ab004abd-d698-4074-9dd1-69b7045387e7",
"order": 0,
"navigationEnabled": true,
"blobLocation": "https://privacyportaltrial-cdn.onetrust.com/preferencecenter-settings/14dae3b8-255e-4f44-afad-d35ee8cf1f4f/370694df-20ac-4105-9a8b-327558e7e70f/pages/ab004abd-d698-4074-9dd1-69b7045387e7.json",
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"languages": [{
"name": "1st Page",
"language": "en-us",
"isDefault": true
}, {
"name": "1eme page",
"language": "fr",
"isDefault": false
}]
}, {
"id": "99818122-df05-4f28-b9cd-e7e6184be684",
"order": 1,
"navigationEnabled": true,
"blobLocation": "https://privacyportaltrial-cdn.onetrust.com/preferencecenter-settings/14dae3b8-255e-4f44-afad-d35ee8cf1f4f/370694df-20ac-4105-9a8b-327558e7e70f/pages/99818122-df05-4f28-b9cd-e7e6184be684.json",
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"languages": [{
"name": "2nd Page",
"language": "en-us",
"isDefault": true
}, {
"name": "2ème page",
"language": "fr",
"isDefault": false
}]
}],
"portalSettings": {
"useTitleImage": true,
"titleImageUrl": "https://privacyportaltrial.onetrust.com/ui/assets/images/consent/header-background.svg",
"title": "Your Preferences",
"hardOptOutFormat": "HIDE",
"reasonsDisplayFormat": "List",
"reasonTriggerCondition": "UnsubscribeAll",
"reasonsAllowOther": false,
"unsubscribeReasons": [],
"enableReasons": false
},
"defaultLanguage": "en-us",
"languages": [{
"language": "en-us",
"isDefault": true
}, {
"language": "fr",
"isDefault": false
}],
"translations": {
"en-us": {
"Consent.Ds.Portal.TopicsLabel": "Topics",
"Consent.Ds.Portal.DataElement.InvalidPhoneNumber": "Invalid phone number",
"Consent.Ds.Portal.InvalidLoginToasterMessage": "There was an error while sending your login request.",
"Consent.Ds.Portal.SubscriptionSettingsLabel": "Subscription Settings",
"Consent.Ds.Portal.LoginWithSSO": "Log in with SSO",
"Consent.Ds.Portal.PreferenceCenterUpdateSuccessPlaceholder": "Thank you! Your preferences have been submitted. Please allow a few minutes for these to be updated.",
"Consent.Ds.Portal.Logout": "Log Out",
"Consent.Ds.Portal.UndoChangesLabel": "Undo Changes",
"Consent.Ds.Portal.RemainingAttempts": "attempt remaining",
"Consent.Ds.Portal.ProfileUpdateError": "Your profile could not be updated",
"Consent.Ds.Portal.HardOptOutLabel": "This purpose is locked because it is subject to a hard opt-out.",
"Consent.Ds.Portal.OtpDisclaimerText": "Didn't receive an access code? Please contact the privacy team or try resubmitting your request.",
"Consent.Ds.Portal.LoginRequestError": "Failed to send login request.",
"Consent.Ds.Portal.AlwaysActiveTooltip": "This purpose is set to always active and cannot be modified.",
"Consent.Ds.Portal.DoubleOptInConfirmationReceived": "Your confirmation has been received.",
"Consent.Ds.Portal.CloseMobileMenu": "Close Menu",
"Consent.Ds.Portal.DataElement.InvalidEmail": "Invalid email address",
"Consent.Ds.Portal.ReasonsLabel": "Unsubscribe Reason",
"Consent.Ds.Portal.ReasonsTitle": "Unsubscribe Successful",
"Consent.Ds.Portal.PreferencesUpdateCancelError": "Your changes were not submitted",
"Consent.Ds.Portal.PreferenceEmailLoginOtpDescription": "A one-time code has been sent to the email you provided. Please enter the code below.",
"Consent.Ds.Portal.Unsubscribed": "You have been unsubscribed",
"Consent.Ds.Portal.Others": "Other",
"Consent.Ds.Portal.Otp": "Enter Passcode",
"Consent.Ds.Portal.TimerDescription": "Otherwise, you will be automatically signed out in:",
"Consent.Ds.Portal.CharacterLimitReached": "Character Limit reached.",
"Consent.Ds.Portal.IncorrectOTPErrorMessage": "Incorrect code. Please try again.",
"Consent.Ds.Portal.SessionExpirationContinueButton": "Continue Session",
"Consent.Ds.Portal.GenericErrorMessage": "Sorry, something went wrong. Please try again.",
"Consent.Ds.Portal.SessionExpirationTitle": "Session Timeout",
"Consent.Ds.Portal.Error": "Error",
"Consent.Ds.Portal.ProfileTitle": "Profile",
"Consent.Ds.Portal.Email": "E-Mail",
"Consent.Ds.Portal.PreferenceCenterUnsubscribeSuccessPlaceholder": "You have successfully unsubscribed.",
"Consent.Ds.Portal.Close": "Close",
"Consent.Ds.Portal.LoginRequestSent": "Login request sent. Please check your email.",
"Consent.Ds.Portal.Send": "Send",
"Consent.Ds.Portal.PreferenceCenterLoginHeadline": "Preferences Login",
"Consent.Ds.Portal.PreferenceCenterTitle": "Your Preferences",
"Consent.Ds.Portal.SessionExpirationCancelButton": "Close",
"Consent.Ds.Portal.ContactAdminMessage": "Unfortunately we are unable to verify your identity at this time. Contact a member of our privacy team or try resubmitting your request.",
"Consent.Ds.Portal.PhoneNumber": "Phone Number",
"Consent.Ds.Portal.Submit": "Submit",
"Consent.Ds.Portal.ProfileUpdateSuccess": "Your profile was updated successfully",
"Consent.Ds.Portal.LoginType": "Login Method",
"Consent.Ds.Portal.UnverifiedPhoneNumberErrorMessage": "Unable to find your entry. Please try again.",
"Consent.Ds.Portal.ReasonsMessage": "We are so sad to see you go! Please indicate the reason for your unsubscription and we will work to improve our service.",
"Consent.Ds.Portal.PreferencesUpdated": "Your preferences have been updated",
"Consent.Ds.Portal.Language": "Language",
"Consent.Ds.Portal.UpdatePreferences": "Update Preferences",
"Consent.Ds.Portal.DefaultChangePreferencesLabel": "Change Preferences",
"Consent.Ds.Portal.PreferenceLoginOtpDescription": "A one-time code has been sent to the phone number you provided. Please enter the code below.",
"Consent.Ds.Portal.SessionExpirationDescription": "Your session is about to expire. If you wish to remain active, please click 'Continue Session'.",
"Consent.Ds.Portal.Resend": "Resend Passcode",
"Consent.Ds.Portal.DoubleOptInLinkError": "This link is no longer valid.",
"Consent.Ds.Portal.UnsubscribeAllLabel": "Unsubscribe All",
"Consent.Ds.Portal.WelcomeMessage": "Welcome Message"
},
"fr": {
"Consent.Ds.Portal.TopicsLabel": "Thèmes",
"Consent.Ds.Portal.DataElement.InvalidPhoneNumber": "Numéro de téléphone incorrect",
"Consent.Ds.Portal.InvalidLoginToasterMessage": "Une erreur s'est produite lors de l'envoi de votre demande de connexion.",
"Consent.Ds.Portal.SubscriptionSettingsLabel": "Paramètres d’abonnement",
"Consent.Ds.Portal.LoginWithSSO": "Se connecter avec l'authentification unique (SSO)",
"Consent.Ds.Portal.PreferenceCenterUpdateSuccessPlaceholder": "Merci ! Vos préférences ont été soumises. La mise à jour peut prendre quelques minutes.",
"Consent.Ds.Portal.Logout": "Déconnexion",
"Consent.Ds.Portal.UndoChangesLabel": "Annuler les modifications",
"Consent.Ds.Portal.RemainingAttempts": "tentative restante",
"Consent.Ds.Portal.ProfileUpdateError": "Votre profil n’a pas pu être mis à jour.",
"Consent.Ds.Portal.HardOptOutLabel": "Cette finalité est verrouillée parce qu’elle est soumise à un opt-out fixe.",
"Consent.Ds.Portal.OtpDisclaimerText": "Si vous n’avez pas reçu un code d’accès, veuillez contacter un membre de votre équipe de confidentialité ou réessayez de soumettre votre demande.",
"Consent.Ds.Portal.LoginRequestError": "La demande de connexion n'a pas pu être envoyée.",
"Consent.Ds.Portal.AlwaysActiveTooltip": "Cette finalité est toujours active et ne peut être modifiée.",
"Consent.Ds.Portal.DoubleOptInConfirmationReceived": "Votre confirmation a bien été reçue.",
"Consent.Ds.Portal.CloseMobileMenu": "Fermer le menu",
"Consent.Ds.Portal.DataElement.InvalidEmail": "Adresse électronique incorrecte",
"Consent.Ds.Portal.ReasonsLabel": "Raison du désabonnement",
"Consent.Ds.Portal.ReasonsTitle": "Désabonnement réussi",
"Consent.Ds.Portal.PreferencesUpdateCancelError": "Vos modifications n'ont pas été soumises.",
"Consent.Ds.Portal.PreferenceEmailLoginOtpDescription": "Un code à usage unique vous a été envoyé par courriel. Veuillez saisir le code ci-dessous.",
"Consent.Ds.Portal.Unsubscribed": "Vous avez été désabonné(e)",
"Consent.Ds.Portal.Others": "Autres",
"Consent.Ds.Portal.Otp": "Code de vérification",
"Consent.Ds.Portal.TimerDescription": "Sinon, vous serez automatiquement déconnecté(e) :",
"Consent.Ds.Portal.CharacterLimitReached": "La limite de caractères a été atteinte.",
"Consent.Ds.Portal.IncorrectOTPErrorMessage": "Code erroné. Veuillez réessayer.",
"Consent.Ds.Portal.SessionExpirationContinueButton": "Continuer la session",
"Consent.Ds.Portal.GenericErrorMessage": "Désolé, un erreur s'est produite. Veuillez réessayer.",
"Consent.Ds.Portal.SessionExpirationTitle": "Délai d’expiration de session",
"Consent.Ds.Portal.Error": "Erreur",
"Consent.Ds.Portal.ProfileTitle": "Profil",
"Consent.Ds.Portal.Email": "Courriel",
"Consent.Ds.Portal.PreferenceCenterUnsubscribeSuccessPlaceholder": "Vous vous êtes désabonné.",
"Consent.Ds.Portal.Close": "Fermer",
"Consent.Ds.Portal.LoginRequestSent": "Demande de connexion envoyée. Veuillez vérifier vos courriels.",
"Consent.Ds.Portal.Send": "Envoyer",
"Consent.Ds.Portal.PreferenceCenterLoginHeadline": "Préférences de connexion",
"Consent.Ds.Portal.PreferenceCenterTitle": "Vos préférences",
"Consent.Ds.Portal.SessionExpirationCancelButton": "Fermer",
"Consent.Ds.Portal.ContactAdminMessage": "Nous n’avons actuellement pas la possibilité de vérifier votre identité. Veuillez contacter un membre de votre équipe de confidentialité ou réessayez de soumettre votre demande.",
"Consent.Ds.Portal.PhoneNumber": "Numéro de téléphone",
"Consent.Ds.Portal.Submit": "Soumettre",
"Consent.Ds.Portal.ProfileUpdateSuccess": "Votre profil a été mis à jour.",
"Consent.Ds.Portal.LoginType": "Méthode de connexion",
"Consent.Ds.Portal.UnverifiedPhoneNumberErrorMessage": "Votre saisie est introuvable. Veuillez réessayer.",
"Consent.Ds.Portal.ReasonsMessage": "Nous sommes désolés de vous voir partir. Veuillez indiquer la raison de votre désabonnement et nous nous efforcerons d'améliorer notre service.",
"Consent.Ds.Portal.PreferencesUpdated": "Vos préférences ont été mises à jour",
"Consent.Ds.Portal.Language": "Langue",
"Consent.Ds.Portal.UpdatePreferences": "Préférences de mise à jour",
"Consent.Ds.Portal.DefaultChangePreferencesLabel": "Modifier les préférences",
"Consent.Ds.Portal.PreferenceLoginOtpDescription": "Un code à usage unique vous a été envoyé par le biais de votre numéro de portable. Veuillez saisir le code ci-dessous.",
"Consent.Ds.Portal.SessionExpirationDescription": "Votre session est sur le point d'expirer. Si vous souhaitez que votre session reste active, veuillez cliquer sur Continuer la session.",
"Consent.Ds.Portal.Resend": "Renvoyer le code",
"Consent.Ds.Portal.DoubleOptInLinkError": "Ce lien n'est plus valide.",
"Consent.Ds.Portal.UnsubscribeAllLabel": "Annuler tous les abonnements",
"Consent.Ds.Portal.WelcomeMessage": "Message d’accueil"
}
},
"preferenceCenterSettings": {
"languages": {
"en-us": {
"changePreferencesLabel": "Change Preferences",
"unsubscribeSuccessLabel": "You have successfully unsubscribed.",
"topicsLabel": "Topics",
"undoChangesLabel": "Undo Changes",
"unsubscribeAllLabel": "Unsubscribe All",
"updateErrorLabel": "Sorry, something went wrong. Please try again.",
"title": "Your Preferences",
"subscriptionSettingsLabel": "Subscription Settings",
"updateSuccessLabel": "Thank you! Your preferences have been submitted. Please allow a few minutes for these to be updated."
},
"fr": {
"title": "Vos préférences",
"changePreferencesLabel": "Préférences de mise à jour",
"undoChangesLabel": "Annuler les modifications",
"updateSuccessLabel": "Vos préférences ont été mises à jour",
"updateErrorLabel": "Désolé, un erreur s'est produite. Veuillez réessayer.",
"subscriptionSettingsLabel": "Paramètres d’abonnement",
"unsubscribeAllLabel": "Annuler tous les abonnements",
"unsubscribeSuccessLabel": "Vous avez été désabonné(e)",
"topicsLabel": "Thèmes",
"isCompleted": true
}
}
},
"blobLocation": "https://privacyportaltrial-cdn.onetrust.com/preferencecenter-settings/14dae3b8-255e-4f44-afad-d35ee8cf1f4f/370694df-20ac-4105-9a8b-327558e7e70f/schema.json",
"enableMultipleIdentities": false,
"displayUnsubscribeAll": true,
"enablePhoneVerification": false,
"phoneVerificationIdentifierType": "Mobile",
"displayNotificationPurpose": true,
"displaySubscribeSettings": true,
"notificationPurpose": {
"id": "f20cb63a-8576-454b-825f-50c1bc2dc14d",
"order": null,
"languages": [{
"name": "Send Notifications about Changes to Preferences",
"description": "Opting out will stop notifications acknowledging consent or changing consent preferences from being sent. Does not impact notices which request confirmation of consent.",
"language": "en-us",
"isDefault": true
}, {
"name": "Envoyer des notifications sur les modifications apportées aux préférences",
"description": "Si vous choisissez l’option Opt-out, vous ne recevrez plus de notification confirmant votre consentement ou sur les modifications de vos préférences en matière de consentement. Cela ne concerne pas les notifications sollicitant la confirmation du consentement.",
"language": "fr",
"isDefault": false
}],
"label": "Send Notifications about Changes to Preferences",
"description": "Opting out will stop notifications acknowledging consent or changing consent preferences from being sent. Does not impact notices which request confirmation of consent.",
"version": 1,
"topics": [],
"customPreferences": [],
"visibility": null
},
"displayPageLevelSubscribeSettings": false,
"autoCheckTopics": false
}
Retrieve the required ID within the Pages attribute
Using the response from the GET /v2/preferencecenters/{preferencecenterid}/schema endpoint, you can retrieve the required page ID within the Pages attribute.
Referencing the Example Response Body returned above, we can see the following Pages attribute.
"{
"pages": [{
"id": "ab004abd-d698-4074-9dd1-69b7045387e7",
"order": 0,
"navigationEnabled": true,
"blobLocation": "https://privacyportaltrial-cdn.onetrust.com/preferencecenter-settings/14dae3b8-255e-4f44-afad-d35ee8cf1f4f/370694df-20ac-4105-9a8b-327558e7e70f/pages/ab004abd-d698-4074-9dd1-69b7045387e7.json",
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"languages": [{
"name": "1st Page",
"language": "en-us",
"isDefault": true
}]
}, {
"id": "99818122-df05-4f28-b9cd-e7e6184be684",
"order": 1,
"navigationEnabled": true,
"blobLocation": "https://privacyportaltrial-cdn.onetrust.com/preferencecenter-settings/14dae3b8-255e-4f44-afad-d35ee8cf1f4f/370694df-20ac-4105-9a8b-327558e7e70f/pages/99818122-df05-4f28-b9cd-e7e6184be684.json",
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"languages": [{
"name": "2nd Page",
"language": "en-us",
"isDefault": true
}]
}],
"
Retrieve the schema for each required page
For each required page, use the GET /v2/preferencecenterpage/{preferencecenterpageid}/schema endpoint to retrieve the preference center page schema for a given Multi Page Preference Center GUID.
Referencing the example Pages attribute above, we can see that there are two pages within the Multi Page Preference Center. You would then make the following two calls.
Example Request for Page 1:
GET https://trial.onetrust.com/api/consentmanager/v2/preferencecenterpage/ab004abd-d698-4074-9dd1-69b7045387e7/schema
Response Body for Page 1:
{
"id": "ab004abd-d698-4074-9dd1-69b7045387e7",
"order": 0,
"isHidden": false,
"navigationEnabled": true,
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"sections": [{
"id": "624f0d70-c288-46f4-8927-8c32ded6c5ea",
"identifierType": "",
"isHeaderHidden": false,
"order": 0,
"conditionalRules": null,
"purposes": [],
"customDataElements": [],
"elements": [],
"languages": [],
"isSubscriptionSettings": true
}, {
"id": "41f04ca9-e787-4a11-9431-18bb3cdbec25",
"identifierType": "",
"isHeaderHidden": false,
"order": 1,
"conditionalRules": null,
"purposes": [{
"id": "f3db79c8-d816-44ad-a0a7-241063fdf5e8",
"order": 1,
"languages": [{
"name": "Newsletter Signup",
"description": "Signup for OT Kicks newsletter",
"language": "en-us",
"isDefault": true
}, {
"name": "Inscription de abonnement",
"description": "Inscription pour OT Kicks",
"language": "fr",
"isDefault": false
}],
"label": "Newsletter Signup",
"description": "Signup for OT Kicks newsletter",
"version": 2,
"topics": [],
"customPreferences": [],
"visibility": "VISIBLE_TO_ALL"
}],
"customDataElements": [],
"elements": [{
"id": "00ac7ae6-9735-49b1-b52d-9fb91158f86b",
"order": 0,
"languages": [{
"content": "<p>Description of section</p>",
"language": "en-us",
"isDefault": true
}, {
"content": "<p>Description de section</p>",
"language": "fr",
"isDefault": false
}]
}],
"languages": [{
"name": "2nd Section",
"language": "en-us",
"isDefault": true
}, {
"name": "2eme section",
"language": "fr",
"isDefault": false
}],
"isSubscriptionSettings": false
}],
"languages": [{
"name": "1st Page",
"language": "en-us",
"isDefault": true
}, {
"name": "1eme page",
"language": "fr",
"isDefault": false
}]
}
Example Request for Page 2:
GET https://trial.onetrust.com/api/consentmanager/v2/preferencecenterpage/99818122-df05-4f28-b9cd-e7e6184be684/schema
Example Response Body for Page 2:
{
"id": "99818122-df05-4f28-b9cd-e7e6184be684",
"order": 1,
"isHidden": false,
"navigationEnabled": true,
"displaySubscribeSettings": true,
"displayUnsubscribeAll": true,
"sections": [{
"id": "6d11c867-4cf3-4d62-9786-92017ec49d58",
"identifierType": "",
"isHeaderHidden": false,
"order": 1,
"conditionalRules": null,
"purposes": [{
"id": "62eae1e5-62bb-4337-8ee3-b4bfe6fb260d",
"order": 1,
"languages": [{
"name": "Publisher Email Marketing",
"description": "email marketing for publisher connect",
"language": "en-us",
"isDefault": true
}, {
"name": "Publisher Email Marketing",
"description": "email marketing pour publisher connect",
"language": "fr",
"isDefault": false
}],
"label": "Publisher Email Marketing",
"description": "email marketing for publisher connect",
"version": 2,
"topics": [],
"customPreferences": [],
"visibility": "VISIBLE_TO_ALL"
}],
"customDataElements": [{
"id": "37a2f038-ea95-4bbe-88d2-8d70273ea3b4",
"order": 2,
"languages": [{
"name": "Address",
"language": "fr"
}],
"name": "Address",
"hidden": false,
"readOnly": false,
"displayAs": "NONE",
"dataElementType": "USER_INPUT",
"dataElementOptions": []
}, {
"id": "f9e5d2d6-4794-4d89-b59b-e52f8b611cc3",
"order": 3,
"languages": [{
"name": "City",
"language": "fr"
}],
"name": "City",
"hidden": false,
"readOnly": false,
"displayAs": "NONE",
"dataElementType": "USER_INPUT",
"dataElementOptions": []
}],
"elements": [{
"id": "aab406b1-bf20-4e40-8acc-9af48a52482c",
"order": 0,
"languages": [{
"content": "<p>Description of section</p>",
"language": "en-us",
"isDefault": true
}, {
"content": "<p>Description de section</p>",
"language": "fr",
"isDefault": false
}]
}],
"languages": [{
"name": "New Section",
"language": "en-us",
"isDefault": true
}, {
"name": "Neuvelle section",
"language": "fr",
"isDefault": false
}],
"isSubscriptionSettings": false
}, {
"id": "ba1f692e-64ec-4983-998f-916615b71c10",
"identifierType": "",
"isHeaderHidden": false,
"order": 0,
"conditionalRules": null,
"purposes": [],
"customDataElements": [],
"elements": [],
"languages": [],
"isSubscriptionSettings": true
}],
"languages": [{
"name": "2nd Page",
"language": "en-us",
"isDefault": true
}, {
"name": "2ème page",
"language": "fr",
"isDefault": false
}]
}
Retrieve the data subject's language and consent status
The GET /v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoint can be used to retrieve a data subject's preferred language and consent status for purposes, topics, and purpose preferences for a given Preference Center GUID.
Note: The required parameters are the unique identifier of the Preference Center, which is denoted as {prefcenterId} and the identifier of the data subject.
Example Request:
GET https://trial.onetrust.com/api/consentmanager/v1/preferencecenters/370694df-20ac-4105-9a8b-327558e7e70f/datasubjects/preferences
--header 'identifier: [email protected]'
Example Response Body:
{
"messages": [],
"DataSubjectId": "[email protected]",
"Language": "en-us",
"Purposes": [
{
"Id": "fc234c93-02c1-4cc3-b11f-2bab88783a13",
"Label": "Hats",
"Description": "Types of Hats",
"Status": "ACTIVE",
"TransactionStatus": "ACTIVE",
"Topics": [],
"CustomPreferences": [
{
"Id": "482f54ad-d259-4096-b2f1-33a164713571",
"Name": "Hat Colors",
"Description": "Select the color hat.",
"SelectionType": "MULTI_CHOICE",
"DisplayAs": "BUTTONS",
"Required": false,
"Options": [
{
"Id": "05fe27b5-8253-4693-9294-5078a3c75685",
"Label": "White"
}
],
"Languages": [
{
"Name": "Hat Colors",
"Description": "Select the color hat.",
"Language": "en-us",
"Default": true,
"Options": [
{
"Id": "05fe27b5-8253-4693-9294-5078a3c75685",
"Label": "White"
},
{
"Id": "71cf1641-d73c-4a68-9f51-a33cc0187ca9",
"Label": "Pink"
},
{
"Id": "362869a8-6c10-4024-8b34-099afcdfdf13",
"Label": "Black"
}
]
}
]
}
]
},
{
"Id": "bcb18434-725b-4d76-8742-2fbe3ce2cf95",
"Label": "Shirts",
"Description": "Types of Shirts",
"Status": "ACTIVE",
"TransactionStatus": "ACTIVE",
"Topics": [],
"CustomPreferences": [
{
"Id": "7bcbb62f-110a-40a6-8373-5abd90378b5a",
"Name": "Shirt Colors",
"Description": "Colors of shirts available ",
"SelectionType": "MULTI_CHOICE",
"DisplayAs": "BUTTONS",
"Required": false,
"Options": [
{
"Id": "1574d675-3a21-4d12-bd62-ff80d0ef79b5",
"Label": "Striped"
}
],
"Languages": [
{
"Name": "Shirt Colors",
"Description": "Colors of shirts available ",
"Language": "en-us",
"Default": true,
"Options": [
{
"Id": "f71d61b4-a938-4466-aad2-a3e6dc1f5609",
"Label": "Red"
},
{
"Id": "1574d675-3a21-4d12-bd62-ff80d0ef79b5",
"Label": "Striped"
},
{
"Id": "b92625a2-867c-42b0-9c85-d4acb872948c",
"Label": "Pink"
},
{
"Id": "5c823fdb-b379-46c9-9914-3df3e1214409",
"Label": "Green"
}
]
}
]
}
]
},
{
"Id": "25f403df-f5e8-42b8-a5b3-9cc6c2d114dc",
"Label": "Restocked Inventory",
"Description": "Blah",
"Status": "ACTIVE",
"TransactionStatus": "WITHDRAWN",
"Topics": [],
"CustomPreferences": []
},
{
"Id": "60047e2d-c63d-48b3-a55b-622ef7d26201",
"Label": "Jeans",
"Description": "Types of Jeans",
"Status": "ACTIVE",
"TransactionStatus": "ACTIVE",
"Topics": [],
"CustomPreferences": []
}
],
"Status": 200,
"DsDataElements": {
"Your Country": "United States",
"Your Birthday": "02/15/1985",
"Name": "John Doe"
}
}
Step 3: Build your Preference Center UI
In this step, you will create logic to loop through the returned JSON objects and output the HTML. To do this, you will:
- Retrieve the data subject's selected language and consent status
- Iterate through the list of purposes, topics, purpose preferences, and options in the preference center schema
- Populate the general labels for the Preference Center
Retrieve the data subject's selected language and consent status
As mentioned in step 2, the GET /v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoint can be used to retrieve the data subject's selected language and consent status for purposes, topics, purpose preferences, and options.
Referencing the Example Response Body returned above, we can see that John Doe's selected language is en-us. This will be used to search the preference center schema for the translation that aligns with the data subject's selected language.
{
"messages": [],
"DataSubjectId": "[email protected]",
"Language": "en-us",
...
}
In addition, the consent status should also be taken into account to determine how each purpose, topic, purpose preference, and option should appear for the data subject within the Preference Center UI.
For example, we can see that John Doe's consent status for the purpose "Jeans" is Active. This should be properly reflected for the data subject within the Preference Center UI.
{
"Id": "60047e2d-c63d-48b3-a55b-622ef7d26201",
"Label": "Jeans",
"Description": "Types of Jeans",
"Status": "ACTIVE",
"TransactionStatus": "ACTIVE",
"Topics": [],
"CustomPreferences": []
}
Iterate through the list of purposes, topics, purpose preferences, and options in the preference center schema
You will search through the preference center schema for the data subject's language to display the purposes, topics, purpose preferences, and options in the appropriate translation within the Preference Center UI.
In addition, you will define how purposes, topics, purpose preferences, and options should display in the Preference Center UI based on the data subject's consent statuses for those elements.
Note: You will also need to set the language in which you want the preference center to appear if the data subject's language is not supported.
To accomplish this:
- Iterate through the list of purposes
- Go through purpose languages for the data subjects's language and use the resulting language to display the purpose label and description.
- Go through the data subject's consent status for each purpose and reflect that status accordingly.
- Iterate through the list of topics
- Go through topic languages for the data subject's language and use the resulting language to display the topic label and description.
- Go through the data subject's consent status for each topic and reflect that status accordingly.
- Iterate through the list of purpose preferences
- Go through purpose preference languages for the data subject's language and use the resulting language to display the purpose preference label and description.
- Go through the data subject's consent status for each purpose preference and reflect that status accordingly.
- Iterate through the list of options
- Go through option languages for the data subject's language and use the resulting language to display option label and description.
- Go through the data subject's consent status for each option and reflect that status accordingly.
Populate the general labels for the Preference Center
You will also need to populate all the general labels for the Preference Center, such as the labels found in the Preference Center Settings part of the GET /v1/preferencecenters/{prefcenterId}/preferences payload.
"preferenceCenterSettings": {
"languages": {
"en-us": {
"changePreferencesLabel": "Change Preferences",
"unsubscribeSuccessLabel": "You have successfully unsubscribed.",
"topicsLabel": "Topics",
"undoChangesLabel": "Undo Changes",
"unsubscribeAllLabel": "Unsubscribe All",
"updateErrorLabel": "Sorry, something went wrong. Please try again.",
"title": "Your Preferences",
"subscriptionSettingsLabel": "Subscription Settings",
"updateSuccessLabel": "Thank you! Your preferences have been submitted. Please allow a few minutes for these to be updated."
},
"fr": {
"title": "Vos préférences",
"changePreferencesLabel": "Préférences de mise à jour",
"undoChangesLabel": "Annuler les modifications",
"updateSuccessLabel": "Vos préférences ont été mises à jour",
"updateErrorLabel": "Désolé, un erreur s'est produite. Veuillez réessayer.",
"subscriptionSettingsLabel": "Paramètres d’abonnement",
"unsubscribeAllLabel": "Annuler tous les abonnements",
"unsubscribeSuccessLabel": "Vous avez été désabonné(e)",
"topicsLabel": "Thèmes",
"isCompleted": true
}
}
Step 4: Use the APIs to update consent preferences
Submit consent preferences using PUT
The PUT /v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoint can be used to update a data subject's preferences for a given Preference Center GUID and Data Subject identifier.
When submitting changes to consent preferences using this call, only pass the IDs of the purposes and preferences for which a data subject has opted-in.
Note: The required parameters are the unique identifier of the Preference Center, which is denoted as {prefcenterId} and the identifier of the data subject.
Example Request:
PUT https://trial.onetrust.com/api/consentmanager/v1/preferencecenters/370694df-20ac-4105-9a8b-327558e7e70f/datasubjects/preferences
--header 'identifier: [email protected]'
Example Request Body:
{
"Purposes": [
{
"Id": "ff5a3df6-7166-4768-9424-af48d4cce842",
"Topics": [],
"CustomPreferences": []
},
{
"Id": "bcb18434-725b-4d76-8742-2fbe3ce2cf95",
"Topics": [],
"CustomPreferences": [
{
"Id": "7bcbb62f-110a-40a6-8373-5abd90378b5a",
"Options": [
{
"Id": "1574d675-3a21-4d12-bd62-ff80d0ef79b5"
},
{
"Id": "f71d61b4-a938-4466-aad2-a3e6dc1f5609"
}
]
}
]
},
{
"Id": "fc234c93-02c1-4cc3-b11f-2bab88783a13",
"Topics": [],
"CustomPreferences": [
{
"Id": "482f54ad-d259-4096-b2f1-33a164713571",
"Options": [
{
"Id": "362869a8-6c10-4024-8b34-099afcdfdf13"
}
]
}
]
}
],
"dsDataElements" : {
"Your Country": "United States",
"Your Birthday": "02/15/1985",
"Name": "John Doe"
}
}
Example Response Body:
{
"Purposes": [
{
"Id": "bcb18434-725b-4d76-8742-2fbe3ce2cf95",
"Status": true,
"ReceiptGuid": "54c464e0-76b2-450f-98ad-956f988a76d9",
"Messages": [
"Purpose updated"
]
},
{
"Id": "fc234c93-02c1-4cc3-b11f-2bab88783a13",
"Status": true,
"ReceiptGuid": "54c464e0-76b2-450f-98ad-956f988a76d9",
"Messages": [
"Purpose updated"
]
},
{
"Id": "60047e2d-c63d-48b3-a55b-622ef7d26201",
"Status": true,
"ReceiptGuid": "54c464e0-76b2-450f-98ad-956f988a76d9",
"Messages": [
"Purpose withdrawn"
]
}
]
}
(Optional) Withdraw all consent using DELETE
If an Unsubscribe All button is provided within the Preference Center, you can use the DELETE
/v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoint to automatically withdraw all of a data subject's consent.
Note: The required parameters are the unique identifier of the Preference Center, which is denoted as {prefcenterId} and the identifier of the data subject.
Example Request:
DELETE https://trial.onetrust.com/api/consentmanager/v1/preferencecenters/370694df-20ac-4105-9a8b-327558e7e70f/datasubjects/preferences
--header 'identifier: [email protected]'
Example Response Body:
{
"Purposes": [
{
"Id": "fc234c93-02c1-4cc3-b11f-2bab88783a13",
"Status": true,
"ReceiptGuid": "bcd0f1f4-7648-4e5c-8ad3-fe72a1c2591e",
"Messages": [
"Purpose withdrawn"
]
},
{
"Id": "bcb18434-725b-4d76-8742-2fbe3ce2cf95",
"Status": true,
"ReceiptGuid": "bcd0f1f4-7648-4e5c-8ad3-fe72a1c2591e",
"Messages": [
"Purpose withdrawn"
]
},
{
"Id": "60047e2d-c63d-48b3-a55b-622ef7d26201",
"Status": true,
"ReceiptGuid": "bcd0f1f4-7648-4e5c-8ad3-fe72a1c2591e",
"Messages": [
"Purpose withdrawn"
]
}
]
}