API Reference

Base URL

https://api.dpdpashield.in

Method 1 - Bearer Token (Dashboard API)

Used for all protected dashboard endpoints. Obtain a token by logging in via POST /api/v1/auth/login. Access tokens expire in 15 minutes; use the refresh token to obtain a new one.

// Send on every request:
Authorization: Bearer <your-jwt-token>

// Obtain a token:
POST /api/v1/auth/login
{
  "email": "dpo@yourcompany.com",
  "password": "..."
}
// Response: { "data": { "token": "eyJ...", "refreshToken": "..." } }

// Refresh when expired:
POST /api/v1/auth/refresh
{ "refreshToken": "..." }
// Response: { "data": { "token": "eyJ..." } }

Method 2 - API Key (SDK / Public Endpoints)

Used by the JavaScript SDK and public-facing endpoints. Passed as a request body field or query parameter. Generate keys in Settings → API Keys.

// As a request body field (SDK endpoints):
{
  "apiKey": "dpdpa_live_YOUR_KEY",
  ...
}

// As a query parameter (GET endpoints):
GET /api/v1/consent/public-notice?apiKey=dpdpa_live_YOUR_KEY

Which auth method for which endpoint?

Returns aggregate consent metrics for the dashboard.

{
  "data": {
    "totalConsents": 4821,
    "consentGiven": 3960,
    "consentWithdrawn": 146,
    "withdrawalRate": 3.0,
    "recentConsents": 312,
    "byPurpose": [
      { "purposeId": "uuid", "name": "Analytics", "given": 2100, "withdrawn": 40 }
    ]
  }
}

Paginated list of consent records. Each record includes the notice version at time of consent - use this to identify stale consents for re-consent campaigns.

{
  "data": {
    "items": [
      {
        "id": "uuid",
        "dataPrincipalHash": "sha256hex",
        "consentGiven": true,
        "languageShown": "HI",
        "positionShown": "bottom-right",
        "isWithdrawn": false,
        "withdrawnAt": null,
        "withdrawnPurposes": [],
        "isPartiallyWithdrawn": false,
        "createdAt": "2026-05-01T10:00:00.000Z",
        "noticeId": "uuid",
        "noticeTitle": "Acme Privacy Notice",
        "noticeVersionNumber": 2,
        "currentNoticeVersion": 3
      }
    ],
    "total": 4821,
    "page": 1,
    "limit": 20
  }
}

Look up consent status by SHA-256 hash of the data principal identifier.

{
  "data": [
    {
      "consentRecordId": "uuid",
      "noticeId": "uuid",
      "noticeTitle": "Acme Privacy Notice",
      "noticeVersion": 3,
      "consentGiven": { "purpose-id-1": true, "purpose-id-2": false },
      "isWithdrawn": false,
      "withdrawnAt": null,
      "withdrawnPurposes": [],
      "isPartiallyWithdrawn": false,
      "createdAt": "2026-05-01T10:00:00.000Z",
      "proofHash": "sha256hex"
    }
  ]
}
// data is an array sorted newest-first.
// Use data[0] for the current state; empty array = no consent on record.
// isWithdrawn is only true on FULL withdrawal - check isPartiallyWithdrawn too,
// since withdrawnAt stays null when only some purposes were revoked.

Record a new consent decision via the dashboard API. For widget-based collection use POST /sdk-record instead.

{
  "noticeId": "550e8400-e29b-41d4-a716-446655440000",
  "dataPrincipalIdentifier": "user@example.com",
  "consentGiven": {
    "purpose-uuid-1": true,
    "purpose-uuid-2": false
  }
}

{
  "data": {
    "consentRecordId": "uuid",
    "proofHash": "sha256-hash-of-canonical-consent-payload",
    "status": "recorded"
  }
}

Withdraw consent on behalf of a data principal (dashboard/DPO action). Creates an immutable WithdrawalRecord and a 7-day ComplianceTask. Use POST /withdraw-public for principal self-service.

Generate a single-use, 7-day withdrawal portal token. The token URL can be emailed to the data principal so they can self-serve withdrawal without authentication.

{
  "data": {
    "token": "wt_abc123...",
    "portalUrl": "https://dpdpashield.in/portal/wt_abc123...",
    "expiresAt": "2026-05-08T10:00:00.000Z"
  }
}

Retrieve portal context for a withdrawal token. Returns the notice and purpose details so the portal can render the consent state.

Redeem a withdrawal token. Used by the /portal/[token] page. Token is consumed after redemption.

List all notices for the tenant. Includes consent count per notice.

Create a new DRAFT consent notice.

Returns the currently published notice. Used by the dashboard notice card.

Fetch a single notice by ID with full purpose config and translation data.

Update a DRAFT notice. All fields are optional (partial update). Returns 409 if notice is PUBLISHED or ARCHIVED - duplicate to a new draft instead.

Publish a DRAFT notice. Atomically archives any existing published notice. Returns materialChangeDetected flag for re-consent campaign prompting.

{
  "data": {
    "id": "uuid",
    "status": "PUBLISHED",
    "versionNumber": 3,
    "materialChangeDetected": true,
    "materialChanges": [
      { "field": "purposes", "type": "added", "isMaterial": true, "newValue": "Marketing" }
    ],
    "fromVersionNumber": 2,
    "toVersionNumber": 3
  }
}

Archive or delete a notice. Behaviour depends on consent history: DRAFT with no consents is hard-deleted; notices with consent records are soft-archived to preserve DPDPA Section 6(10) proof evidence.

{
  "data": {
    "action": "ARCHIVED",  // or "DELETED"
    "noticeId": "uuid",
    "consentCount": 1240,
    "message": "Notice archived and preserved for compliance records."
  }
}

Returns the full version history (immutable snapshots) for a notice, ordered by version number descending.

Field-by-field diff between two notice versions. Returns hasMaterialChange: true if any purpose, data category, or legal basis changed - signals re-consent is needed.

{
  "data": {
    "from": 2,
    "to": 3,
    "hasMaterialChange": true,
    "totalChanges": 2,
    "changes": [
      {
        "field": "purposes",
        "type": "added",
        "isMaterial": true,
        "newValue": "Marketing Communications"
      },
      {
        "field": "title",
        "type": "modified",
        "isMaterial": false,
        "oldValue": "Privacy Notice v2",
        "newValue": "Privacy Notice v3"
      }
    ]
  }
}

Preview how a notice will render in a given language. Returns translated fields if available, falls back to English.

Add a translation for a specific language. Supports all 22 scheduled Indian languages per DPDPA.

List all translations for a notice.

Update an existing translation. :lang is the uppercase language code (e.g. HI, TA).

Remove a translation for a specific language.

One-click auto-translate to all 22 scheduled Indian languages via google-translate-api-x. Translations can be reviewed and edited before publishing.

Set or clear the DPDPA Rule 3 withdrawal URL on a notice - works on PUBLISHED notices without requiring a full draft-and-publish cycle.

List all webhook configurations for the tenant.

{
  "data": [
    {
      "id": "uuid",
      "label": "Production Events",
      "url": "https://yourserver.com/webhooks/dpdpa",
      "events": ["consent.recorded", "consent.withdrawn"],
      "isActive": true,
      "createdAt": "2026-01-15T00:00:00.000Z"
    }
  ]
}

Create a new webhook. The secret is used to sign deliveries - store it securely and never expose it client-side.

consent.recorded      // New consent decision recorded
consent.withdrawn     // Consent withdrawn by data principal
notice.published      // Consent notice published or updated
rights.submitted      // Data principal rights request submitted
breach.created        // Breach incident created

Update an existing webhook. All fields are optional. Use isActive: false to temporarily disable.

Permanently delete a webhook configuration and its delivery history.

View delivery history for a webhook - useful for debugging failed deliveries.

{
  "data": [
    {
      "id": "uuid",
      "event": "consent.recorded",
      "statusCode": 200,
      "deliveredAt": "2026-05-01T10:00:00.000Z",
      "attempts": 1,
      "success": true
    }
  ]
}

Send a test event to the webhook URL to verify connectivity and signature verification. Sends a sample consent.recorded payload.

// Each delivery includes:
// X-DPDPAShield-Signature: sha256=<hmac-hex>
// X-DPDPAShield-Event: consent.recorded
// X-DPDPAShield-Timestamp: 1746720000000

import { createHmac } from 'crypto'

function verifySignature(payload: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

Upsert the tenant's CMP config. Validates the merged state (existing + incoming fields) against child-directed rules before saving - see CHILD_DIRECTED_VIOLATION below.

List or batch-upsert (max 200 per call) the declared tracker registry. Trackers found by the automated scanner set declaredByAdmin: false; manually declared trackers set it true.

Accept/reject/partial rates, per-category opt-in rate, and a daily time series for the dashboard chart. Query params: from, to (max 365-day range).

Triggers an on-demand headless crawl of your configured scanUrls. Returns 202 immediately with a scanRunId - poll GET /api/v1/cmp/scan-runs to check completion. A DPO alert email fires automatically only when the scan finds genuinely new, previously-undeclared trackers.

GET /cmp/translations lists label sets; POST /cmp/translations/draft (body: { language }) AI-drafts one language; POST /cmp/translations/draft-all drafts all 22 in one call (capped at 3 runs/tenant/day); PUT /cmp/translations/:language saves edited labels and marks status: REVIEWED.