Compliance API Reference

Programmatic access to privacy and compliance features

Overview

The Compliance API allows you to programmatically manage data subject requests, consent records, and compliance scanning. Use this API to integrate privacy features into your applications or automate compliance workflows.

Base URL: https://your-server.com/api/compliance

Authentication

All API requests require authentication using a Bearer token:

Authorization: Bearer your-api-key

Get your API key from Settings → API Keys → Create New Key with compliance scope.

Endpoints

Data Subject Requests (DSR)

List All Requests

GET /api/compliance/dsr

Query Parameters:

Parameter	Type	Description
`status`	string	Filter by status: `pending`, `processing`, `completed`, `rejected`
`type`	string	Filter by type: `access`, `deletion`, `rectification`, `portability`, `objection`
`from`	date	Start date (YYYY-MM-DD)
`to`	date	End date (YYYY-MM-DD)
`limit`	number	Results per page (default: 20, max: 100)
`offset`	number	Pagination offset

Example Request:

GET /api/compliance/dsr?status=pending&limit=10

Example Response:

{
  "total": 7,
  "limit": 10,
  "offset": 0,
  "requests": [
    {
      "id": "DSR-2025-0142",
      "type": "access",
      "status": "pending",
      "userId": "usr_abc123",
      "email": "john.doe@email.com",
      "submittedAt": "2025-05-13T10:30:00Z",
      "dueDate": "2025-05-28T10:30:00Z",
      "assignee": null
    },
    {
      "id": "DSR-2025-0141",
      "type": "deletion",
      "status": "processing",
      "userId": "usr_def456",
      "email": "sarah@company.com",
      "submittedAt": "2025-05-10T14:15:00Z",
      "dueDate": "2025-05-25T14:15:00Z",
      "assignee": "admin@company.com"
    }
  ]
}

Get Single Request

GET /api/compliance/dsr/{id}

Example Response:

{
  "id": "DSR-2025-0142",
  "type": "access",
  "status": "pending",
  "userId": "usr_abc123",
  "email": "john.doe@email.com",
  "name": "John Doe",
  "submittedAt": "2025-05-13T10:30:00Z",
  "dueDate": "2025-05-28T10:30:00Z",
  "assignee": null,
  "message": "I would like a copy of all my data",
  "verifiedAt": "2025-05-13T10:35:00Z",
  "dataFound": {
    "profile": true,
    "conversations": true,
    "consents": true,
    "activityLogs": true
  },
  "history": [
    {
      "action": "created",
      "timestamp": "2025-05-13T10:30:00Z",
      "actor": "system"
    },
    {
      "action": "verified",
      "timestamp": "2025-05-13T10:35:00Z",
      "actor": "system"
    }
  ]
}

Create Request

POST /api/compliance/dsr

Request Body:

Field	Type	Required	Description
`type`	string	Yes	`access`, `deletion`, `rectification`, `portability`, `objection`
`email`	string	Yes	User’s email address
`userId`	string	No	User ID if known
`message`	string	No	User’s message/reason
`skipVerification`	boolean	No	Skip email verification (default: false)

Example Request:

POST /api/compliance/dsr
Content-Type: application/json

{
  "type": "access",
  "email": "john.doe@email.com",
  "message": "Please provide all my personal data"
}

Example Response:

{
  "id": "DSR-2025-0143",
  "type": "access",
  "status": "pending_verification",
  "email": "john.doe@email.com",
  "submittedAt": "2025-05-15T14:00:00Z",
  "dueDate": "2025-05-30T14:00:00Z",
  "verificationSent": true
}

Update Request Status

PATCH /api/compliance/dsr/{id}

Request Body:

Field	Type	Description
`status`	string	`processing`, `completed`, `rejected`
`assignee`	string	Email of person handling request
`notes`	string	Internal notes
`rejectionReason`	string	Required if status is `rejected`

Example Request:

PATCH /api/compliance/dsr/DSR-2025-0142
Content-Type: application/json

{
  "status": "processing",
  "assignee": "admin@company.com"
}

Complete Request (with data package)

POST /api/compliance/dsr/{id}/complete

Request Body:

Field	Type	Description
`notifyUser`	boolean	Send completion email (default: true)
`dataPackageUrl`	string	URL to downloadable data (for access/portability)
`expiresAt`	datetime	When download link expires

Example Request:

POST /api/compliance/dsr/DSR-2025-0142/complete
Content-Type: application/json

{
  "notifyUser": true,
  "dataPackageUrl": "https://secure.company.com/data/abc123.zip",
  "expiresAt": "2025-06-15T00:00:00Z"
}

GET /api/compliance/consent/{userId}

Example Response:

{
  "userId": "usr_abc123",
  "email": "john.doe@email.com",
  "consents": [
    {
      "type": "terms_of_service",
      "status": "given",
      "version": "2.3",
      "timestamp": "2025-01-15T10:32:00Z",
      "method": "web_form",
      "ip": "192.168.1.100"
    },
    {
      "type": "marketing",
      "status": "given",
      "timestamp": "2025-01-15T10:32:00Z",
      "method": "web_form"
    },
    {
      "type": "analytics",
      "status": "withdrawn",
      "timestamp": "2025-03-22T15:15:00Z",
      "method": "preference_center"
    }
  ]
}

POST /api/compliance/consent

Request Body:

Field	Type	Required	Description
`userId`	string	Yes	User identifier
`email`	string	Yes	User’s email
`type`	string	Yes	Consent type (e.g., `marketing`, `analytics`)
`status`	string	Yes	`given` or `withdrawn`
`method`	string	No	How consent was collected
`ip`	string	No	User’s IP address
`userAgent`	string	No	User’s browser

Example Request:

POST /api/compliance/consent
Content-Type: application/json

{
  "userId": "usr_abc123",
  "email": "john.doe@email.com",
  "type": "marketing",
  "status": "given",
  "method": "chatbot",
  "ip": "192.168.1.100"
}

Example Response:

{
  "success": true,
  "consentId": "con_xyz789",
  "userId": "usr_abc123",
  "type": "marketing",
  "status": "given",
  "timestamp": "2025-05-15T14:30:00Z"
}

DELETE /api/compliance/consent/{userId}/{type}

Example Request:

DELETE /api/compliance/consent/usr_abc123/marketing

Example Response:

{
  "success": true,
  "userId": "usr_abc123",
  "type": "marketing",
  "status": "withdrawn",
  "timestamp": "2025-05-15T14:35:00Z"
}

GET /api/compliance/consent-types

Example Response:

{
  "consentTypes": [
    {
      "id": "terms_of_service",
      "name": "Terms of Service",
      "required": true,
      "description": "Agreement to terms and conditions",
      "currentVersion": "2.3"
    },
    {
      "id": "marketing",
      "name": "Marketing Communications",
      "required": false,
      "description": "Receive promotional emails and offers"
    },
    {
      "id": "analytics",
      "name": "Analytics & Improvement",
      "required": false,
      "description": "Help us improve by analyzing usage patterns"
    }
  ]
}

Compliance Scanning

Start a Scan

POST /api/compliance/scan

Request Body:

Field	Type	Description
`type`	string	`quick`, `full`, or `custom`
`targets`	array	For custom: `["bots", "kb", "users", "logs"]`
`botId`	string	Scan specific bot only

Example Request:

POST /api/compliance/scan
Content-Type: application/json

{
  "type": "full",
  "targets": ["bots", "kb", "users", "logs"]
}

Example Response:

{
  "scanId": "scan_20250515_001",
  "status": "running",
  "type": "full",
  "startedAt": "2025-05-15T14:45:00Z",
  "estimatedDuration": "30 minutes"
}

Get Scan Status

GET /api/compliance/scan/{scanId}

Example Response (In Progress):

{
  "scanId": "scan_20250515_001",
  "status": "running",
  "progress": 45,
  "currentStep": "Scanning conversation logs",
  "startedAt": "2025-05-15T14:45:00Z"
}

Example Response (Complete):

{
  "scanId": "scan_20250515_001",
  "status": "completed",
  "progress": 100,
  "startedAt": "2025-05-15T14:45:00Z",
  "completedAt": "2025-05-15T15:12:00Z",
  "summary": {
    "totalChecks": 148,
    "passed": 145,
    "warnings": 2,
    "critical": 1
  },
  "issues": [
    {
      "severity": "critical",
      "type": "unencrypted_pii",
      "description": "Unencrypted PII found in conversation logs",
      "location": "support-bot/logs/2025-05-10",
      "affectedRecords": 23,
      "recommendation": "Enable automatic PII redaction"
    },
    {
      "severity": "warning",
      "type": "consent_expiring",
      "description": "Consent records older than 2 years",
      "affectedUsers": 12,
      "recommendation": "Send consent renewal requests"
    }
  ]
}

Get Latest Scan Results

GET /api/compliance/scan/latest

Returns the most recent completed scan results.

Reports

Generate Compliance Report

POST /api/compliance/report

Request Body:

Field	Type	Description
`type`	string	`summary`, `detailed`, `audit`
`period`	string	`last_30_days`, `last_90_days`, `year`, `custom`
`from`	date	Start date for custom period
`to`	date	End date for custom period
`format`	string	`json`, `pdf`, `csv`

Example Request:

POST /api/compliance/report
Content-Type: application/json

{
  "type": "summary",
  "period": "last_30_days",
  "format": "json"
}

Example Response:

{
  "reportId": "rpt_20250515_001",
  "generatedAt": "2025-05-15T15:00:00Z",
  "period": {
    "from": "2025-04-15",
    "to": "2025-05-15"
  },
  "summary": {
    "overallScore": 92,
    "dsrRequests": {
      "received": 15,
      "completed": 12,
      "pending": 3,
      "averageResponseDays": 8.5
    },
    "consentRate": 94.2,
    "dataBreaches": 0,
    "scansPerformed": 4,
    "issuesFound": 7,
    "issuesResolved": 5
  }
}

Download Report

GET /api/compliance/report/{reportId}/download

Returns the report file in the requested format.

Data Deletion

Delete User Data

DELETE /api/compliance/user/{userId}/data

Query Parameters:

Parameter	Type	Description
`scope`	string	`all`, `conversations`, `profile`, `analytics`
`confirm`	boolean	Must be `true` to execute

Example Request:

DELETE /api/compliance/user/usr_abc123/data?scope=all&confirm=true

Example Response:

{
  "success": true,
  "userId": "usr_abc123",
  "deletedAt": "2025-05-15T15:30:00Z",
  "scope": "all",
  "itemsDeleted": {
    "profile": 1,
    "conversations": 45,
    "consents": 3,
    "activityLogs": 234
  },
  "retainedForLegal": {
    "auditLogs": 15
  }
}

Error Responses

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable message",
    "details": {}
  }
}

Common Error Codes:

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	API key lacks required scope
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request parameters
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error

Rate Limits

Endpoint	Limit
All endpoints	100 requests/minute
Scan endpoints	5 requests/hour
Report generation	10 requests/hour

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1621234567

Webhooks

Configure webhooks to receive real-time notifications.

Available Events:

Event	Description
`dsr.created`	New DSR submitted
`dsr.completed`	DSR marked complete
`dsr.due_soon`	DSR due within 3 days
`consent.changed`	User consent updated
`scan.completed`	Compliance scan finished
`issue.critical`	Critical issue detected

Webhook Payload Example:

POST https://your-server.com/webhook
Content-Type: application/json
X-Signature: sha256=...

{
  "event": "dsr.created",
  "timestamp": "2025-05-15T14:00:00Z",
  "data": {
    "id": "DSR-2025-0143",
    "type": "access",
    "email": "user@example.com"
  }
}

General Bots Documentation

Compliance API Reference

Overview

Authentication

Endpoints

Data Subject Requests (DSR)

List All Requests

Get Single Request

Create Request

Update Request Status

Complete Request (with data package)

Compliance Scanning

Start a Scan

Get Scan Status

Get Latest Scan Results

Reports

Generate Compliance Report

Download Report

Data Deletion

Delete User Data

Error Responses

Rate Limits

Webhooks

See Also

Keyboard shortcuts

General Bots Documentation