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

# List Consent Records

> List all DPDP consent records for the developer, with optional filtering by data principal.

## Endpoint

```
GET /v1/dpdp/consent-records
```

## Authentication

Requires a developer API key in the `Authorization` header.

## Request Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer <api_key>` |

## Query Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `dataPrincipalId` | `string` | No | Filter records by data principal ID |
| `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

```bash theme={null}
curl "https://api.grantex.dev/v1/dpdp/consent-records?dataPrincipalId=user_abc123" \
  -H "Authorization: Bearer gx_..."
```

## Response -- 200 OK

```json theme={null}
{
  "records": [
    {
      "recordId": "crec_01HXYZ...",
      "grantId": "grnt_01HXYZ...",
      "dataPrincipalId": "user_abc123",
      "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 |
| - | - | - |
| `records` | `object[]` | One page of consent records, newest first |
| `totalRecords` | `number` | Total number of records matching the filter, across all pages |
| `nextCursor` | `string \| null` | Pass as `cursor` for the next page; `null` on the last page |

Without `limit` or `cursor` the list returns what it always did: the newest
100 records unfiltered (with a `nextCursor` when there are more), and every
matching record with `dataPrincipalId` (`nextCursor` is `null`). Sending
`limit` or `cursor` pages: 50 records by default and at most 200; follow
`nextCursor` to read them all.

### Record Object

| Field | Type | Description |
| - | - | - |
| `recordId` | `string` | Unique consent record ID |
| `grantId` | `string` | The associated grant ID |
| `dataPrincipalId` | `string` | The data principal who gave consent |
| `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](/api-reference/dpdp/consent-notice-content#the-notice-hash)); `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 |

## Error Responses

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

## SDK Examples

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Grantex } from '@grantex/sdk';

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

  // List all consent records
  const all = await grantex.dpdp.listConsentRecords();

  // Filter by data principal
  const filtered = await grantex.dpdp.listConsentRecords('user_abc123');
  ```

  ```python Python theme={null}
  from grantex import Grantex

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

  # List all consent records
  all_records = grantex.dpdp.list_consent_records()

  # Filter by data principal
  filtered = grantex.dpdp.list_consent_records(principal_id="user_abc123")
  ```
</CodeGroup>

These SDK calls read the first page. To pass `limit` and `cursor`, use the
REST call above unless your SDK version lists them.

## Ownership

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.