> ## 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 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

```bash theme={null}
curl https://grantex-auth-dd4mtrt2gq-uc.a.run.app/v1/dpdp/data-principals/user_abc123/records \
  -H "Authorization: Bearer gx_..."
```

## Response -- 200 OK

```json theme={null}
{
  "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                                              |

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

## 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_...' });

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

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

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

  result = grantex.dpdp.list_principal_records("user_abc123")
  print(result.records, result.total_records)
  ```
</CodeGroup>