API Reference - PrivionGRC Developer Documentation

Overview

The PrivionGRC Public API allows you to integrate data privacy workflows into your applications, websites, and systems. Submit DSR requests, create and manage DPIA workflows, and maintain RoPA records with our comprehensive REST API that follows RESTful principles and returns JSON responses.

API Information

Version: 1.0
Base URL: https://app.priviongrc.com/api
Authentication: API Key (Header-based)
Format: JSON

Key Features

GDPR-Compliant DSR Intake - Submit data subject requests programmatically
DPIA Workflow Management - Create and manage Data Protection Impact Assessments (Article 35)
RoPA Record Management - Maintain Records of Processing Activities (Article 30)
Automatic Deadline Tracking - 30-day GDPR compliance built-in
Real-time Status Updates - Check DSR, DPIA, and RoPA status anytime
Secure API Key Authentication - Organization-level access control
Rate Limiting - Fair usage policies with clear headers
Comprehensive Audit Logs - Full compliance trail

Authentication

All API requests require an API key passed in the X-API-Key header.

Getting Your API Key

Log into your PrivionGRC account
Navigate to Settings → API Keys
Click Generate New API Key
Choose environment (Production or Test)
Save your key securely (you won't see it again!)

API Key Format

Production: org_live_AbCdEf123456789XyZ...
Test:       org_test_AbCdEf123456789XyZ...

Using Your API Key

POST /api/public/dsr HTTP/1.1
Host: app.priviongrc.com
Content-Type: application/json
X-API-Key: org_live_your_key_here

{
  "request_type": "access",
  "data_subject_name": "John Doe",
  "data_subject_email": "john@example.com"
}

Security Best Practices

⚠️ Never expose API keys in client-side code (JavaScript, mobile apps)
✅ Use API keys only from server-side code
✅ Rotate keys regularly
✅ Use different keys for different environments
✅ Revoke keys immediately if compromised

Rate Limiting

API requests are rate limited per API key to ensure fair usage and system stability.

Default Limits

Environment	Requests per Minute	Requests per Hour
Production	60	1,000
Test	10	100

Rate Limit Headers

Every API response includes rate limit information:

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 2025-10-16T10:30:00Z

Rate Limit Exceeded

When you exceed the rate limit, you'll receive a 429 Too Many Requests response:

{
  "error": "Rate limit exceeded",
  "message": "Maximum 60 requests per minute",
  "retryAfter": 42
}

Wait for the retryAfter seconds before making another request.

Error Handling

The API uses conventional HTTP status codes and returns consistent error responses.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Missing or invalid API key
403	Forbidden - API key lacks permission
404	Not Found
429	Rate Limit Exceeded
500	Internal Server Error

Error Response Format

{
  "error": "Validation error",
  "message": "data_subject_email is required",
  "details": {
    "field": "data_subject_email",
    "code": "required_field"
  }
}

Endpoints

DSR Management

Submit and manage Data Subject Rights (DSR) requests programmatically.

POST/api/public/dsr

Submit a new DSR request

Authentication

Required

Permission

dsr:create

Rate Limit

10 requests/minute

Request Body

{
  "request_type": "access",
  "data_subject_name": "John Doe",
  "data_subject_email": "john.doe@example.com",
  "data_subject_phone": "+1-555-0123",
  "description": "User requested copy of all personal data",
  "priority": "normal",
  "source": "website_form",
  "external_reference_id": "ticket-12345"
}

Parameters

Field	Type	Required	Description
request_type	string	✅ Yes	Type of DSR. One of: access, erasure, rectification, portability, object, restrict
data_subject_name	string	✅ Yes	Full name of the data subject
data_subject_email	string	✅ Yes	Valid email address of the data subject
data_subject_phone	string	No	Phone number of the data subject
description	string	No	Additional details about the request
priority	string	No	Priority level. One of: low, normal, high, urgent. Default: normal
source	string	No	Source of the request (e.g., "website_form", "mobile_app"). Default: api
external_reference_id	string	No	Your internal reference ID for tracking

Response

Success (201 Created):

{
  "success": true,
  "message": "DSR request created successfully",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "request_type": "access",
    "status": "pending",
    "received_date": "2025-10-16T10:15:30Z",
    "due_date": "2025-11-15T10:15:30Z",
    "reference_number": "a1b2c3d4"
  },
  "note": "We will process your request within 30 days as required by GDPR Article 12(3)"
}

Error (400 Bad Request):

{
  "error": "Validation error",
  "message": "request_type must be one of: access, erasure, rectification, portability, object, restrict"
}

Examples

cURL:

curl -X POST https://app.priviongrc.com/api/public/dsr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: org_live_your_key_here" \
  -d '{
    "request_type": "access",
    "data_subject_name": "John Doe",
    "data_subject_email": "john.doe@example.com",
    "description": "User requested data export"
  }'

JavaScript:

const response = await fetch('https://app.priviongrc.com/api/public/dsr', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'org_live_your_key_here'
  },
  body: JSON.stringify({
    request_type: 'access',
    data_subject_name: 'John Doe',
    data_subject_email: 'john.doe@example.com',
    description: 'User requested data export'
  })
});

const data = await response.json();
console.log('DSR created:', data);

GET/api/public/dsr/:id

Retrieve the status of a DSR request

Authentication

Required

Permission

dsr:read

Rate Limit

60 requests/minute

Path Parameters

Parameter	Type	Description
id	string	The DSR request ID (UUID)

Response

Success (200 OK):

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "request_type": "access",
    "status": "in_progress",
    "received_date": "2025-10-16T10:15:30Z",
    "due_date": "2025-11-15T10:15:30Z",
    "priority": "normal"
  }
}

Error (404 Not Found):

{
  "error": "Not found",
  "message": "DSR request not found"
}

Example

curl -X GET https://app.priviongrc.com/api/public/dsr/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "X-API-Key: org_live_your_key_here"

DPIA Management

Create and manage Data Protection Impact Assessment (DPIA) workflows for GDPR Article 35 compliance. Complete CRUD operations with risk assessment and DPO consultation tracking.

GET/api/public/dpia

List DPIA workflows with filtering

Authentication

Required

Permission

dpia:read

Query Parameters

status - draft|pending|in-progress|completed|rejected
risk_level - low|medium|high|critical
limit - 1-100 (default: 50)
offset - pagination offset

Example Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "project_name": "Customer Analytics Platform DPIA",
      "risk_level": "medium",
      "status": "completed",
      "created_at": "2025-01-01T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 15,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

POST/api/public/dpia

Create new DPIA workflow

Authentication

Required

Permission

dpia:create

Request Body

{
  "project_name": "Marketing Campaign Analytics DPIA",
  "description": "DPIA for automated marketing campaigns",
  "risk_level": "high",
  "identified_risks": [
    "Privacy intrusion risk",
    "Data profiling concerns"
  ],
  "mitigation_measures": [
    "Data minimization",
    "User consent mechanisms"
  ],
  "status": "draft"
}

GET/api/public/dpia/:id

Retrieve a specific DPIA workflow

Authentication

Required

Permission

dpia:read

Path Parameters

Parameter	Type	Description
id	string	The DPIA workflow ID (UUID)

Example Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "project_name": "Customer Analytics Platform DPIA",
    "description": "DPIA for customer analytics platform",
    "risk_level": "medium",
    "status": "completed",
    "identified_risks": [
      "Privacy intrusion risk",
      "Data profiling concerns"
    ],
    "mitigation_measures": [
      "Data minimization",
      "User consent mechanisms"
    ],
    "created_at": "2025-01-01T08:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Example

curl -X GET https://app.priviongrc.com/api/public/dpia/uuid \
  -H "X-API-Key: org_live_your_key_here"

PUT/api/public/dpia/:id

Update an existing DPIA workflow

Authentication

Required

Permission

dpia:update

Request Body

{
  "project_name": "Updated Analytics System DPIA",
  "description": "Updated DPIA description",
  "risk_level": "low",
  "identified_risks": [
    "Minimal privacy risk"
  ],
  "mitigation_measures": [
    "Data minimization implemented"
  ],
  "status": "completed"
}

Example

curl -X PUT https://app.priviongrc.com/api/public/dpia/uuid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: org_live_your_key_here" \
  -d '{
    "status": "completed",
    "risk_level": "low"
  }'

RoPA Management

Create and maintain Records of Processing Activities (RoPA) for GDPR Article 30 compliance. Full CRUD operations with automatic organization scoping.

GET/api/public/ropa

List RoPA records with filtering

Authentication

Required

Permission

ropa:read

Query Parameters

status - active|inactive|archived
limit - 1-100 (default: 50)
offset - pagination offset

Example Response

{
  "success": true,
  "data": [
    {
      "id": "uuid",
      "name": "Customer Service Processing",
      "legal_basis": "contract",
      "status": "active",
      "created_at": "2025-01-01T08:00:00Z"
    }
  ],
  "pagination": {
    "total": 25,
    "limit": 50,
    "offset": 0,
    "has_more": false
  }
}

POST/api/public/ropa

Create new RoPA record

Authentication

Required

Permission

ropa:create

Request Body

{
  "name": "Marketing Campaign Processing",
  "description": "Processing personal data for marketing campaigns",
  "processing_purpose": "Marketing campaign effectiveness analysis",
  "legal_basis": "consent",
  "data_subjects": ["customers", "website_visitors"],
  "data_categories": ["email_address", "browser_data"],
  "retention_period": "2 years",
  "status": "active"
}

GET/api/public/ropa/:id

Retrieve a specific RoPA record

Authentication

Required

Permission

ropa:read

Path Parameters

Parameter	Type	Description
id	string	The RoPA record ID (UUID)

Example Response

{
  "success": true,
  "data": {
    "id": "uuid",
    "name": "Customer Service Processing",
    "description": "Processing personal data for customer service",
    "processing_purpose": "Customer support and service delivery",
    "legal_basis": "contract",
    "data_subjects": ["customers"],
    "data_categories": ["contact_info", "service_history"],
    "retention_period": "7 years",
    "status": "active",
    "created_at": "2025-01-01T08:00:00Z",
    "updated_at": "2025-01-15T10:30:00Z"
  }
}

Example

curl -X GET https://app.priviongrc.com/api/public/ropa/uuid \
  -H "X-API-Key: org_live_your_key_here"

PUT/api/public/ropa/:id

Update an existing RoPA record

Authentication

Required

Permission

ropa:update

Request Body

{
  "name": "Updated Marketing Processing",
  "description": "Updated processing description",
  "processing_purpose": "Marketing campaign effectiveness analysis",
  "legal_basis": "consent",
  "data_subjects": ["customers", "website_visitors"],
  "data_categories": ["email_address", "browser_data"],
  "retention_period": "3 years",
  "status": "inactive"
}

Example

curl -X PUT https://app.priviongrc.com/api/public/ropa/uuid \
  -H "Content-Type: application/json" \
  -H "X-API-Key: org_live_your_key_here" \
  -d '{
    "status": "inactive",
    "retention_period": "3 years"
  }'

DSR Request Types

GDPR Article References

Request Type	GDPR Article	Description	Typical Use Case
access	Article 15	Right of Access	User wants copy of their data
erasure	Article 17	Right to be Forgotten	User wants data deleted
rectification	Article 16	Right to Rectification	User wants data corrected
portability	Article 20	Data Portability	User wants data in machine-readable format
object	Article 21	Right to Object	User objects to processing
restrict	Article 18	Restriction of Processing	User wants processing limited

Webhooks (Coming Soon)

Future releases will support webhooks for real-time notifications:

DSR status changes
Assignment notifications
Completion notifications
Deadline warnings

SDKs & Libraries

Official SDKs (Coming Soon)

•JavaScript/TypeScript - npm package
•Python - PyPI package
•PHP - Composer package
•Ruby - RubyGems package

Community SDKs

Have you built a client library? Let us know!

Support

Need Help?

📧Email: api@priviongrc.com
📚Documentation: https://docs.priviongrc.com
💬Support Portal: https://support.priviongrc.com

Report Issues

Found a bug or have a feature request? Open an issue on our GitHub repository.

Terms of Use

By using the PrivionGRC API, you agree to our Terms of Service and Privacy Policy.

Fair Use Policy

Use API keys securely
Respect rate limits
Don't abuse the service
Follow GDPR and data protection laws

Violations may result in API key suspension or account termination.

Last Updated: October 16, 2025

API Version: 1.0