The Preference Center APIs can be used to build out custom Preference Centers using the Original or Enhanced templates. The following steps outline how you can make use of the Preference Center schema to build out your custom preference center.
- Complete the following in the OneTrust application
2. Create purposes, topics, and custom preferences
3. Obtain the Preference Center UID
4. Create OAuth 2.0 Credentials and generate a token - Retrieve the preference center 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 custom preferences
- Create a Preference Center using the Original or Enhanced template
- Obtain the Preference Center GUID
- Create OAuth 2.0 Credentials and generate a token
Create purposes, topics, and custom preferences
In the OneTrust application, first create purposes, topics, and custom 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 custom preferences using the POST /v1/custompreferences endpoint.
Create a Preference Center using the Original or Enhanced template
On the Preference Centers screen, create a preference center using either the Original or Enhanced template. For more information, see Managing Preference Centers Using the Original or Enhanced Template 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 schema and the data subject's language and consent status
In this step, you will use the GET /v1/preferencecenters/{prefcenterId}/preferences endpoint and the GET /v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoint. The responses you receive from these API calls will be used to build your Preference Center UI in step 3.
- Retrieve the preference center schema
- Retrieve the data subject's language and consent status
Retrieve the preference center schema
The GET /v1/preferencecenters/{prefcenterId}/preferences endpoint can be used to retrieve the preference center schema for a given Preference Center UUID.
Note: The Unique identifier of the Preference center denoted as {prefcenterId}.
Example Request:
GET https://trial.onetrust.com/api/consentmanager/v1/preferencecenters/823e68b8-9b25-4191-a912-25d4d8e96e5b/preferences
Example Response Body:
{
"messages": [],
"PreferenceCentreId": "823e68b8-9b25-4191-a912-25d4d8e96e5b",
"Purposes": [
{
"Id": "fc234c93-02c1-4cc3-b11f-2bab88783a13",
"Version": 1,
"Label": "Hats",
"Description": "Types of Hats",
"Status": "ACTIVE",
"PurposeType": "STANDARD",
"Languages": [
{
"Name": "Hats",
"Description": "Types of Hats",
"Language": "en-us",
"Default": true
}
],
"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"
},
{
"Id": "71cf1641-d73c-4a68-9f51-a33cc0187ca9",
"Label": "Pink"
},
{
"Id": "362869a8-6c10-4024-8b34-099afcdfdf13",
"Label": "Black"
}
],
"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"
}
]
}
]
}
],
"LifeSpan": 0,
"DefaultConsentStatus": "OPT_OUT"
},
{
"Id": "bcb18434-725b-4d76-8742-2fbe3ce2cf95",
"Version": 1,
"Label": "Shirts",
"Description": "Types of Shirts",
"Status": "ACTIVE",
"PurposeType": "STANDARD",
"Languages": [
{
"Name": "Shirts",
"Description": "Types of Shirts",
"Language": "en-us",
"Default": true
}
],
"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": "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"
}
],
"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"
}
]
}
]
}
],
"LifeSpan": 0,
"DefaultConsentStatus": "OPT_OUT"
},
{
"Id": "25f403df-f5e8-42b8-a5b3-9cc6c2d114dc",
"Version": 1,
"Label": "Restocked Inventory",
"Description": "Blah",
"Status": "ACTIVE",
"PurposeType": "STANDARD",
"Languages": [
{
"Name": "Restocked Inventory",
"Description": "Blah",
"Language": "en-us",
"Default": true
}
],
"Topics": [],
"CustomPreferences": [],
"LifeSpan": 0,
"DefaultConsentStatus": "OPT_OUT"
},
{
"Id": "ff5a3df6-7166-4768-9424-af48d4cce842",
"Version": 1,
"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.",
"Status": "ACTIVE",
"PurposeType": "NOTIFICATION_OPT_OUT",
"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",
"Default": 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",
"Default": false
},
{
"Name": "Benachrichtigungen über Änderungen der Präferenzen senden",
"Description": "Durch Abmeldung wird das Versenden von Benachrichtigungen, die Einwilligungen oder Änderungen der Einwilligungspräferenzen bestätigen, unterbunden. Dies hat keine Auswirkungen auf Benachrichtigungen, die eine Einwilligungsbestätigung anfordern.",
"Language": "de",
"Default": false
},
{
"Name": "Envío de notificaciones sobre cambios en las preferencias",
"Description": "Si cancela la suscripción, no recibirá notificaciones sobre la aceptación de las selecciones de consentimiento o cambios en las preferencias. Esta acción no afecta las notificaciones en las que se solicita su confirmación de consentimiento.",
"Language": "es",
"Default": false
},
{
"Name": "Invio notifiche relative alle modifiche alle preferenze",
"Description": "Il rifiuto esplicito interrompe l'invio di notifiche di riconoscimento del consenso o di modifica delle preferenze di consenso. Non influisce sulle notifiche che richiedono la conferma del consenso.",
"Language": "it",
"Default": false
},
{
"Name": "Verzenden van meldingen over wijzigingen in voorkeursinstellingen",
"Description": "Als u zich afmeldt zult u geen meldingen meer ontvangen waarmee toestemmingsselecties worden bevestigd of wijzigingen in de voorkeursinstellingen worden gemeld. Dit heeft geen invloed op berichten waarin om uw bevestiging van een toestemmingsselectie ",
"Language": "nl",
"Default": false
},
{
"Name": "Send meddelelser om Ændringer i Præferencer",
"Description": "Hvis du vælger at framelde dig, vil du samtidig blokere meddelelser om anerkendelse af samtykke samt anerkendelse af, at ændringer i samtykkepræferencer ikke vil blive meddelt. Dette påvirker ikke meddelelser, der anmoder om bekræftelse af samtykke.",
"Language": "da",
"Default": false
},
{
"Name": "優先設定の変更に関する通知を送信する",
"Description": "オプトアウトすると、同意を受理したことに関する、または同意の優先設定変更に関する通知の送信を停止します。同意の確認を必要とする通知には影響はありません。",
"Language": "ja",
"Default": false
},
{
"Name": "Enviar notificações sobre alterações às preferências",
"Description": "Optar ativamente por não participar porá fim ao envio de notificações de reconhecimento do consentimento ou de alterações das preferências do consentimento. Não afeta avisos que solicitem a confirmação do consentimento.",
"Language": "pt",
"Default": false
},
{
"Name": "Trimiterea notificărilor privind modificările aduse preferințelor",
"Description": "Dacă alegeți opțiunea de renunțare, nu veți mai primi o notificare care să confirme acordul dvs. sau modificările aduse preferințelor dvs. de consimțământ. Acest lucru nu se aplică notificărilor care necesită confirmarea consimțământului.",
"Language": "ro",
"Default": false
},
{
"Name": "Poslat oznámení o změně předvoleb",
"Description": "Pokud toto neaktivujete, nebudou se odesílat oznámení o obdržení souhlasu nebo o změně předvoleb souvisejících se souhlasem. Netýká se to oznámení, která vyžadují potvrzení o obdržení souhlasu.",
"Language": "cs",
"Default": false
}
],
"Topics": [],
"CustomPreferences": [],
"LifeSpan": 0,
"DefaultConsentStatus": "ACTIVE"
},
{
"Id": "60047e2d-c63d-48b3-a55b-622ef7d26201",
"Version": 3,
"Label": "Jeans",
"Description": "Types of Jeans",
"Status": "ACTIVE",
"PurposeType": "STANDARD",
"Languages": [
{
"Name": "Jeans",
"Description": "Types of Jeans",
"Language": "en-us",
"Default": true
},
{
"Name": "Jeans - Spanish",
"Description": "Types of Jeans - Spanish",
"Language": "es",
"Default": false
}
],
"Topics": [],
"CustomPreferences": [],
"LifeSpan": 0,
"DefaultConsentStatus": "OPT_OUT"
}
],
"Status": 200,
"PreferenceCenterSettings": {
"Languages": {
"en-us": {
"TopicsLabel": "Topics",
"UnsubscribeAllLabel": "Unsubscribe All",
"UndoChangesLabel": "Undo Changes",
"UpdateErrorLabel": "Sorry, something went wrong. Please try again.",
"Title": "Preference Management 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.",
"WelcomeMessage": "<p>Welcome to your preference center! Here, you will be able to manage your profile and preferences.</p>",
"UnsubscribeSuccessLabel": "You have successfully unsubscribed.",
"UpdateSuccessLabel": "Thank you! Your preferences have been submitted. Please allow a few minutes for these to be updated.",
"SubscriptionSettingsLabel": "Subscription Settings",
"ChangePreferencesLabel": "Save Your Preferences",
"ReasonsTitle": "Unsubscribe Successful",
"ReasonsLabel": "Unsubscribe Reason"
}
},
"Order": 1
},
"PortalSettings": {
"UseTitleImage": true,
"TitleImageUrl": "https://lkgb-portal.1trust.app/ui/assets/images/consent/header-background.svg",
"Title": "Your Preferences"
},
"Language": "en-us",
"Languages": [
"en-us"
],
"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.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.PreferencesUpdateCancelError": "Your changes were not submitted",
"Consent.Ds.Portal.ReasonsTitle": "Unsubscribe Successful",
"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.PreferenceCenterLoginHeadline": "Preferences Login",
"Consent.Ds.Portal.Send": "Send",
"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.ProfileUpdateSuccess": "Your profile was updated successfully",
"Consent.Ds.Portal.Submit": "Submit",
"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"
}
},
"DisplayNotificationPurpose": true,
"Template": "ENHANCED",
"ProfileSettings": {
"Order": 2,
"DataElements": [
{
"Id": "d23a2186-850e-42ac-a400-11e5b124ac99",
"Label": "Your Birthday",
"IsIdentifier": false,
"Hidden": false,
"ReadOnly": false,
"Status": "PUBLISHED",
"Languages": [],
"DisplayAs": "NONE",
"DataElementType": "DATE_PICKER",
"DataElementOptions": []
},
{
"Id": "02e3da1b-0a04-4c7b-bece-4a1adc123d67",
"Label": "Your Country",
"IsIdentifier": false,
"Hidden": false,
"ReadOnly": false,
"Status": "PUBLISHED",
"Languages": [],
"DisplayAs": "NONE",
"DataElementType": "COUNTRY",
"DataElementOptions": []
},
{
"Id": "b02aad95-2ad4-4f8d-b57c-853f74815d77",
"Label": "Name",
"IsIdentifier": false,
"Hidden": false,
"ReadOnly": false,
"Status": "PUBLISHED",
"Languages": [
{
"Name": "Pais",
"DataElementOptions": [],
"Language": "es"
},
{
"Name": "Nom",
"DataElementOptions": [],
"Language": "fr"
}
],
"DisplayAs": null,
"DataElementType": "USER_INPUT",
"DataElementOptions": []
}
],
"Languages": {
"en-us": {}
},
"IsEnabled": true,
"DefaultTitle": "Profile"
}
}
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 custom 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/823e68b8-9b25-4191-a912-25d4d8e96e5b/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, custom 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, custom 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, custom 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, custom 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, custom preferences, and options in the appropriate translation within the Preference Center UI.
In addition, you will define how purposes, topics, custom 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 custom preferences
- Go through custom preference languages for the data subject's language and use the resulting language to display the customer preference label and description.
- Go through the data subject's consent status for each custom 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": {
"TopicsLabel": "Topics",
"UnsubscribeAllLabel": "Unsubscribe All",
"UndoChangesLabel": "Undo Changes",
"UpdateErrorLabel": "Sorry, something went wrong. Please try again.",
"Title": "Preference Management 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.",
"WelcomeMessage": "<p>Welcome to your preference center! Here, you will be able to manage your profile and preferences.</p>",
"UnsubscribeSuccessLabel": "You have successfully unsubscribed.",
"UpdateSuccessLabel": "Thank you! Your preferences have been submitted. Please allow a few minutes for these to be updated.",
"SubscriptionSettingsLabel": "Subscription Settings",
"ChangePreferencesLabel": "Save Your Preferences",
"ReasonsTitle": "Unsubscribe Successful",
"ReasonsLabel": "Unsubscribe Reason"
}
},
...
}
Step 4: Use the APIs to update consent preferences
You can then use the PUT /v1/preferencecenters/{prefcenterId}/datasubjects/preferences and DELETE
/v1/preferencecenters/{prefcenterId}/datasubjects/preferences endpoints to pass changes in a data subject's consent preferences to your custom Preference Center.
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/823e68b8-9b25-4191-a912-25d4d8e96e5b/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"
]
}
]
}
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/823e68b8-9b25-4191-a912-25d4d8e96e5b/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"
]
}
]
}