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

# File Grievance

> Record a grievance from a data principal, with the response period the Data Fiduciary publishes (DPDP Act s.13; DPDP Rules 2025 r.14(3): at most 90 days).

## Endpoint

```
POST /v1/dpdp/grievances
```

## Authentication

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

## Request Headers

| Header | Value |
| - | - |
| `Authorization` | `Bearer <api_key>` |
| `Content-Type` | `application/json` |

## Request Body

| Field | Type | Required | Description |
| - | - | - | - |
| `dataPrincipalId` | `string` | Yes | The data principal filing the grievance |
| `type` | `string` | Yes | Grievance type (e.g., `"consent-violation"`, `"data-breach"`, `"unauthorized-processing"`) |
| `description` | `string` | Yes | Detailed description of the grievance |
| `recordId` | `string` | No | Related consent record ID. It must be one of the developer's records, about this `dataPrincipalId` |
| `evidence` | `object` | No | Supporting evidence as a JSON object (up to 16 KB) |
| `responsePeriodDays` | `integer` | No | The response period the Data Fiduciary publishes, 1 to 90 days. The default of 7 is a product default, not a statutory period: DPDP Rules 2025 r.14(3) require the fiduciary to publish its period, which may not exceed 90 days |

## Example Request

```bash theme={null}
curl -X POST https://api.grantex.dev/v1/dpdp/grievances \
  -H "Authorization: Bearer gx_..." \
  -H "Content-Type: application/json" \
  -d '{
    "dataPrincipalId": "user_abc123",
    "type": "unauthorized-processing",
    "description": "Data was processed beyond the consented purposes",
    "recordId": "crec_01HXYZ...",
    "evidence": {
      "observedAction": "marketing emails sent without consent",
      "timestamp": "2026-04-04T10:00:00.000Z"
    }
  }'
```

## Response -- 202 Accepted

```json theme={null}
{
  "grievanceId": "grv_01HXYZ...",
  "referenceNumber": "GRV-2026-01JAB3XK7Q9M2V5W8Y0Z4C6D1E",
  "type": "unauthorized-processing",
  "status": "submitted",
  "responsePeriodDays": 7,
  "expectedResolutionBy": "2026-04-12T14:00:00.000Z",
  "createdAt": "2026-04-05T14:00:00.000Z"
}
```

## Response Fields

| Field | Type | Description |
| - | - | - |
| `grievanceId` | `string` | Unique grievance ID |
| `referenceNumber` | `string` | Human-readable reference number (format: `GRV-YYYY-<ULID>`, not sequential) |
| `type` | `string` | Grievance type |
| `status` | `string` | Initial status: `submitted` |
| `responsePeriodDays` | `integer` | The response period applied |
| `expectedResolutionBy` | `string` | ISO-8601 deadline: filing time plus `responsePeriodDays` |
| `createdAt` | `string` | ISO-8601 creation timestamp |

## Error Responses

| Status | Code | Description |
| - | - | - |
| 400 | `BAD_REQUEST` | Missing required fields (`dataPrincipalId`, `type`, `description`), `responsePeriodDays` outside 1 to 90, or malformed `evidence` |
| 400 | `INVALID_RECORD` | `recordId` is not one of the developer's records, or is about another data principal |
| 401 | `UNAUTHORIZED` | Invalid or missing API key |

Filing is recorded on the audit chain as `grantex.dpdp.grievance_filed`. Move
a grievance through review with [Update Grievance](/api-reference/dpdp/update-grievance)
and list grievances with [List Grievances](/api-reference/dpdp/list-grievances).

## SDK Examples

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

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

  const grievance = await grantex.dpdp.fileGrievance({
    dataPrincipalId: 'user_abc123',
    type: 'unauthorized-processing',
    description: 'Data was processed beyond consented purposes',
    recordId: 'crec_01HXYZ...',
  });
  // grievance.referenceNumber → "GRV-2026-01JAB3XK7Q9M2V5W8Y0Z4C6D1E"
  ```

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

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

  grievance = grantex.dpdp.file_grievance(
      FileGrievanceParams(
          data_principal_id="user_abc123",
          type="unauthorized-processing",
          description="Data was processed beyond consented purposes",
          record_id="crec_01HXYZ...",
      )
  )
  ```
</CodeGroup>

To send `responsePeriodDays`, use the REST call above unless your SDK version
lists the field.

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