List Principal Records

Retrieve all consent records for a specific data principal. Implements the right to access under DPDP Section 11.

Endpoint

GET /v1/dpdp/data-principals/:principalId/records

Authentication

Requires a developer API key in the Authorization header.

Request Headers

Header	Value
Authorization	Bearer <api_key>

Path Parameters

Parameter	Type	Required	Description
principalId	string	Yes	The data principal ID

Example Request

curl https://api.grantex.dev/v1/dpdp/data-principals/user_abc123/records \
  -H "Authorization: Bearer gx_..."

Response — 200 OK

{
  "dataPrincipalId": "user_abc123",
  "records": [
    {
      "recordId": "cr_01HXYZ...",
      "grantId": "grnt_01HXYZ...",
      "dataFiduciaryName": "Acme Corp",
      "purposes": [
        { "code": "analytics", "description": "Usage analytics" }
      ],
      "scopes": ["calendar:read"],
      "consentNoticeId": "notice_v2",
      "status": "active",
      "consentGivenAt": "2026-04-05T12:00:00.000Z",
      "processingExpiresAt": "2027-01-01T00:00:00.000Z",
      "retentionUntil": "2027-01-31T00:00:00.000Z",
      "accessCount": 3,
      "lastAccessedAt": "2026-04-05T14:00:00.000Z",
      "withdrawnAt": null,
      "withdrawnReason": null,
      "createdAt": "2026-04-05T12:00:00.000Z"
    }
  ],
  "totalRecords": 1
}

Response Fields

Field	Type	Description
dataPrincipalId	string	The data principal ID
records	object[]	Array of consent record objects
totalRecords	number	Total number of records

Record Object

Field	Type	Description
recordId	string	Unique consent record ID
grantId	string	The associated grant ID
dataFiduciaryName	string	Name of the data fiduciary (developer)
purposes	object[]	Array of purpose objects ({ code, description })
scopes	string[]	Scopes from the associated grant
consentNoticeId	string	ID of the consent notice
status	string	Record status: active, withdrawn, expired, or erased
consentGivenAt	string	ISO-8601 timestamp of original consent
processingExpiresAt	string	ISO-8601 processing expiry timestamp
retentionUntil	string	ISO-8601 data retention limit
accessCount	number	Number of times this record has been accessed (incremented on each call)
lastAccessedAt	string	ISO-8601 timestamp of last access
withdrawnAt	string | null	ISO-8601 timestamp of withdrawal (if withdrawn)
withdrawnReason	string | null	Reason for withdrawal (if withdrawn)
createdAt	string	ISO-8601 creation timestamp

Each call to this endpoint increments the accessCount on all returned records, providing a built-in audit trail of data access for DPDP compliance.

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Invalid or missing API key

SDK Examples

TypeScript

import Grantex from '@grantex/sdk';

const grantex = new Grantex({ apiKey: 'gx_...' });

const { records, totalRecords } = await grantex.dpdp.listPrincipalRecords('user_abc123');

from grantex import Grantex

grantex = Grantex(api_key="gx_...")

result = grantex.dpdp.list_principal_records("user_abc123")
print(result.records, result.total_records)