List Principal Records

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

Query Parameters

Parameter	Type	Required	Description
`limit`	`integer`	No	Page size, 1 to 200 (default 50 once paging). Sending `limit` or `cursor` turns paging on
`cursor`	`string`	No	The `nextCursor` of the previous page

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": "crec_01HXYZ...",
      "grantId": "grnt_01HXYZ...",
      "dataFiduciaryName": "Example Retail Ltd",
      "purposes": [
        { "code": "analytics", "description": "Usage analytics" }
      ],
      "scopes": ["calendar:read"],
      "consentNoticeId": "notice_v2",
      "consentNoticeVersion": "2.0",
      "consentNoticeLanguage": "en",
      "noticeHash": "9f8e7d6c5b4a...",
      "status": "active",
      "consentGivenAt": "2026-04-05T12:00:00.000Z",
      "processingExpiresAt": "2027-01-01T00:00:00.000Z",
      "retentionUntil": "2027-01-31T00:00:00.000Z",
      "accessCount": 0,
      "lastAccessedAt": null,
      "withdrawnAt": null,
      "withdrawnReason": null,
      "erasedAt": null,
      "createdAt": "2026-04-05T12:00:00.000Z"
    }
  ],
  "totalRecords": 1,
  "nextCursor": null
}

Response Fields

Field	Type	Description
`dataPrincipalId`	`string`	The data principal ID
`records`	`object[]`	One page of consent records, newest first
`totalRecords`	`number`	Total number of the principal’s records, across all pages
`nextCursor`	`string \| null`	Pass as `cursor` for the next page; `null` on the last page

Without limit or cursor every record of the principal is returned, as before, and nextCursor is null. Sending limit or cursor pages: 50 records by default and at most 200.

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
`consentNoticeVersion`	`string \| null`	The notice version the record was given against (`null` for an older record whose version could not be recovered)
`consentNoticeLanguage`	`string \| null`	The language of that notice (`null` when not known for an older record)
`noticeHash`	`string \| null`	The notice hash of that notice, also signed into the proof (Consent Notice Content); `null` for records created before it was kept
`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`	The stored access count. Developer reads through this API do not change it
`lastAccessedAt`	`string \| null`	The stored last-access timestamp, `null` if never set. Developer reads do not change it
`withdrawnAt`	`string \| null`	ISO-8601 timestamp of withdrawal (if withdrawn)
`withdrawnReason`	`string \| null`	Reason for withdrawal (if withdrawn)
`erasedAt`	`string \| null`	ISO-8601 timestamp of erasure (if erased)
`createdAt`	`string`	ISO-8601 creation timestamp

This is a developer read, not the data principal’s own access: it has no side effects and does not change accessCount or lastAccessedAt. (It used to increment them on every call.)

Error Responses

Status	Code	Description
401	`UNAUTHORIZED`	Invalid or missing API key

SDK Examples

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)

Ownership

Grantex is owned by Orchestrum Technologies LLP. Inventor and owner: Sanjeev Kumar. Ownership contact: sanjeev@orchestrum.in or mishra.sanjeev@gmail.com.

Last modified on September 30, 2026

Overview

System

Authentication

Agents

Authorization

Tokens

Events

Grants

Audit

Policies

Webhooks

Billing

Anomalies

Compliance

SCIM

SSO

Principal Sessions

Consent

WebAuthn / FIDO

Budgets

Domains

Usage

Vault

Offline

Verifiable Credentials

DPDP Compliance

DID

List Principal Records

Endpoint

Authentication

Request Headers

Path Parameters

Query Parameters

Example Request

Response — 200 OK

Response Fields

Record Object

Error Responses

SDK Examples

Ownership

​Endpoint

​Authentication

​Request Headers

​Path Parameters

​Query Parameters

​Example Request

​Response — 200 OK

​Response Fields

​Record Object

​Error Responses

​SDK Examples

​Ownership

Endpoint

Authentication

Request Headers

Path Parameters

Query Parameters

Example Request

Response — 200 OK

Response Fields

Record Object

Error Responses

SDK Examples

Ownership