> ## Documentation Index
> Fetch the complete documentation index at: https://developer.onetrust.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introducing the V4 Data Subjects APIs

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.

> 📘
>
> Click API title names below to navigate to the corresponding v4 endpoint.

# [Get Data Subject](https://developer.onetrust.com/onetrust/reference/getdatasubjectbasicdetailsv4)

### Required Parameters

* `identifier`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
     --header 'accept: application/json' \
     --header 'identifier: <IDENTIFIER>'
```
```Text v2
curl --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
     --header 'accept: application/json' \
     --header 'identifier: IDENTIFIER'
```
```Text v3
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.

# [Get Data Subject Details](https://developer.onetrust.com/onetrust/reference/getdatasubjectdetailsv4)

### Required Parameters

* `identifier`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
     --header 'accept: application/json' \
     --header 'identifier: <IDENTIFIER>'
```
```Text v2
curl --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
     --header 'accept: application/json'
```
```Text v3
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.

# [Get List of Data Subjects](https://developer.onetrust.com/onetrust/reference/getdatasubjectsv4)

### Required Parameters

None

### Equivalents

```Text v1
curl --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles \
     --header 'accept: application/json'
```
```Text v2
curl --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
     --header 'accept: application/json'
```
```Text v3
curl --request GET \
     --url https://customer.my.onetrust.com/rest/api/preferences/v3/datasubject-profiles \
     --header 'accept: application/json'
```

# [Get Purpose Details by Data Subject](https://developer.onetrust.com/onetrust/reference/getdatasubjectprofilev4)

### Required Parameters

* `identifier`
* `purposeGuid`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
     --header 'accept: application/json' \
     --header 'identifier: <IDENTIFIER>'
```
```Text v2
Not applicable
```
```Text v3
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.

# [Get List of All Purpose Details by Data Subject](https://developer.onetrust.com/onetrust/reference/getallprofilesbydatasubjectv4)

### Required Parameters

* `identifier`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/datasubjects/profiles?size=20' \
     --header 'accept: application/json' \
     --header 'identifier: <IDENTIFIER>'
```
```Text v2
curl --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v2/datasubjects \
     --header 'accept: application/json' \
     --header 'identifier: IDENTIFIER'
```
```Text v3
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.

# [Get List of All Purpose Details for All Data Subjects](https://developer.onetrust.com/onetrust/reference/getdatasubjectprofilesv4)

### Required Parameters

* `updatedSince`
* `updatedUntil`

### Equivalents

```Text v1
Not applicable
```
```Text v2
Not applicable
```
```Text v3
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.

# [Get Data Subject Token](https://developer.onetrust.com/onetrust/reference/getemaillinktokenbydatasubjectv4)

### Required Parameters

* `identifier`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/linktokens?page=0&size=20' \
     --header 'accept: application/json' \
     --header 'identifier: IDENTIFIER'
```
```Text v2
Not applicable
```
```Text v3
Not applicable
```

### What's new

This API allows you to retrieve the link token for a specific data subject.

# [Get List of Data Subject Tokens](https://developer.onetrust.com/onetrust/reference/getemaillinktokenslistv4)

### Required Parameters

* `fromDate`
* `toDate`

### Equivalents

```Text v1
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v1/linktokens?page=0&size=20' \
     --header 'accept: application/json' \
```
```Text v2
Not applicable
```
```Text v3
Not applicable
```

### What's new

This v4 API allows you to retrieve all link tokens. You must use `requestContinuation` token for pagination.

# [Get List of Data Subject Group Associations by Data Subject](https://developer.onetrust.com/onetrust/reference/getlinkedidentitygroupsbydatasubjectv4)

### Required Parameters

* `identifier`

### Equivalents

```Text v1
Not applicable
```
```Text v2
curl --request GET \
     --url 'https://customer.my.onetrust.com/api/consentmanager/v2/linkedidentitygroups?page=0&size=20' \
     --header 'accept: application/json' \
     --header 'primaryDataSubjectIdentifier: IDENTIFIER'
```
```Text v3
Not applicable
```

# [Get List of Data Subject Group Members](https://developer.onetrust.com/onetrust/reference/getlinkedidentitygroupmembersv4)

### Required Parameters

* `linkedIdentityGroupId`

### Equivalents

```Text v1
Not applicable
```
```Text v2
url --request GET \
     --url https://customer.my.onetrust.com/api/consentmanager/v2/linkedidentitygroups/linkedIdentityGroupId \
     --header 'accept: application/json'
```
```Text v3
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](https://my.onetrust.com/s/contactsupport) in myOneTrust.

![](https://files.readme.io/fff5cc6ca26cfe2a667d5f563f4e926974f75e83b9668c2357c51bc02f968604-image.png)

> 📘
>
> 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.