Please contact your account representative or OneTrust Support for assistance if you need help with the migration.
This guide outlines how to transition from OneTrust’s v1/datasubjects/profiles (Get List of Data Subjects API) to the v4 suite. V4 provides a modular, performant, and more predictable experience.
Key differences between v1 and v4
| Feature | v1 | v4 |
|---|---|---|
| Endpoint | /v1/datasubjects/profiles | Multiple (/v4/datasubjects, /v4/datasubjects/details, /v4/datasubjects/profiles, etc.) |
| Response | Monolithic, nested, large | Modular, granular, purpose-driven. |
| Filtering | Query params + headers | Strict query/header separation, improved filters. |
| Pagination | requestContinuation only | Standard page, size, and requestContinuation support. |
| Purpose Details | Embedded under data subject record | Separated under purpose-specific endpoints. |
Endpoint Mapping Guide
| V1 Feature | V4 Equivalent |
|---|---|
| Get all data subjects with preferences | GET /v4/datasubjects (basic), GET /v4/datasubjects/details (detailed). |
| Filter by purpose | Use /v4/datasubjects/profiles/{purposeGuid} with identifier header. |
| Get purpose history per data subject | GET /v4/datasubjects/ds-profiles (all purposes per data subject). |
| Get updated records across data subjects | GET /v4/datasubjects/profiles (date range, status, etc.) |
Schema Comparison (v1 vs. v4)
| Field Name | V1 Location | V4 Location | Notes |
|---|---|---|---|
identifier | DataSubjectProfile.Identifier | DataSubjectResponseDto.identifier | Renamed and separated. |
Purposes | Nested under each data subject | Retrieved via separate endpoints | Now modular. |
CustomPreferences | Nested under Purposes | Present under ds-profiles | Structure consistent but split. |
Notices | Nested under data subject | Optional parameter in details | Controlled via query param. |
requestContinuation | Required for pagination | Optional and supports page and size | More flexible and RESTful. |
Migration recommendations
- Define your use cases: Whether you need full data subject records or just consent status for a given purpose, select the v4 API that best fits your needs.
- Refactor pagination: Replace legacy
requestContinuationlogic with v4-style pagination, which includespage,size, andsortsupport. - Adjust filtering: Migrate from v1's hybrid query/header filter model to v4's consistent and stricter structure.
- Test in staging: Response payloads and field structures have changed significantly. Make sure to validate any contract updates to ensure compatibility.
- Handle rate limits: Watch for new rate-limiting headers such as
Retry-After,ot-ratelimit-event-id, and other headers along with backoff logic.
Benefits at a glance
V4 delivers faster, clearer, and more reliable APIs for modern consent and preference use cases. While v1 combined everything into a single massive response, v4 gives you tools to precisely control and extract what you need.
Transitioning to v4 APIs will bring significant benefits, including better performance, improved maintainability, and more transparent consent data workflows.