Our latest Data Subjects highly available APIs focus on improving Data Subjects APIs by offering more targeted queries to increase efficiency by providing faster response times. The examples below show the new v4 endpoints and their equivalent versions. In addition, the required parameters for transitioning to the new version are provided along with the differences that the new endpoints present.
For more information, click API titles to navigate to the corresponding v4 endpoint.
Required Parameters
identifier
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
--header 'accept: application/json' \
--header 'identifier: <IDENTIFIER>'
curl --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
url --request GET \
--url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubjects/profile \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
What's new
In v4, this API provides the data subject details at the identity level (i.e., no consent level information), minimizing the data parsing process and improving performance speed.
Required Parameters
identifier
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
--header 'accept: application/json' \
--header 'identifier: <IDENTIFIER>'
curl --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
--header 'accept: application/json'
url --request GET \
--url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubjects/profile \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
What's new
In v4, this API expands on the basic details of a data subject and can be used to retrieve more details of a data subject, including purpose information.
Required Parameters
None
Equivalents
curl --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles \
--header 'accept: application/json'
curl --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
--header 'accept: application/json'
curl --request GET \
--url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubject-profiles \
--header 'accept: application/json'
Required Parameters
identifierpurposeGuid
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
--header 'accept: application/json' \
--header 'identifier: <IDENTIFIER>'
Not applicable
url --request GET \
--url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubjects/profile \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
What's new
This v4 API allows you to retrieve specific purpose information for a data subject.
Required Parameters
identifier
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
--header 'accept: application/json' \
--header 'identifier: <IDENTIFIER>'
curl --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
url --request GET \
--url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubjects/profile \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
What's new
This v4 API is most similar to what v1 and v3 do, returning all purpose information for a given data subject.
Required Parameters
updatedSinceupdatedUntil
Equivalents
Not applicable
Not applicable
Not applicable
What's new
This new v4 API allows you to extract purpose details by last collection point, purpose and/or status. This cannot be achieved using the v1 or v3 endpoints.
Required Parameters
identifier
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/linktokens?page=0&size=20' \
--header 'accept: application/json' \
--header 'identifier: IDENTIFIER'
Not applicable
Not applicable
What's new
This API allows you to retrieve the link token for a specific data subject.
Required Parameters
fromDatetoDate
Equivalents
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v1/linktokens?page=0&size=20' \
--header 'accept: application/json' \
Not applicable
Not applicable
What's new
This v4 API allows you to retrieve all link tokens. You must use requestContinuation token for pagination.
Required Parameters
identifier
Equivalents
Not applicable
curl --request GET \
--url 'https://customer.my.onetrust.com/api/consentmanager/v2/linkedidentitygroups?page=0&size=20' \
--header 'accept: application/json' \
--header 'primaryDataSubjectIdentifier: IDENTIFIER'
Not applicable
Required Parameters
linkedIdentityGroupId
Equivalents
Not applicable
url --request GET \
--url https://customer.my.onetrust.com/api/consentmanager/v2/linkedidentitygroups/linkedIdentityGroupId \
--header 'accept: application/json'
Not applicable
FAQs
1. Is there an impact to my magic links?
No, the same magic links will be available in v4.
2. When should I switch over to v4?
After the v4 migration is done, all of your data will be accessible in v4. Workflows using v1, v2, or v3 data subjects should be updated as soon as possible to v4.
3. Is there any downtime to the tenant when the migration takes place?
No, there will be no interruptions during this process and you will be able to access and use the system during that period.
4. Will I be able to use the rest of Consent APIs and versions when I enable v4?
Yes, previous API versions will also be available after enabling v4.
5. How can I get help to understand what to change in my implementation?
We suggest using this guide. If you have premier support, you can also submit an Ask the Expert request via Get Help in myOneTrust.
If you do not see the Ask the Expert option, please reach out to your OneTrust Customer Success Manager (CSM) or any other person that regularly engages with your CSM to discuss direct or indirect access to the Expert Portal that is included with our Premier Success package subscription.
6. What happens to my data when enabling Data Subjects v4 APIs?
When v4 is enabled:
- Your data is copied from SQL (used by v1 /datasubjects) to Cosmos (used by v4 /datasubjects).
- The SQL data remains intact. It is not removed or altered during this process.
7. Does data continue to write to SQL after enabling v4?
Yes, data continues to write to SQL as usual. Additionally, every write to SQL triggers a parallel write to Cosmos.
8. What happens to historic data when I enable v4?
All historic data is copied from SQL to Cosmos during the initial setup. This ensures that v4 APIs have access to the same comprehensive data set.
9. Will the most recent data be available across both API versions?
Yes, whenever data is upserted into Cosmos, events are triggered to ensure synchronization. Both v1 and v4 API calls within workflows will always retrieve the most up-to-date data.