Consent API Reference
Complete API reference for recording and managing consent events.
Record Consent
POST /api/v1/consent
Request Body
{
"policyVersionId": "uuid-of-policy-version",
"userReference": "user_123",
"userEmail": "user@example.com",
"consentGiven": true,
"metadata": {
"source": "signup_form",
"campaign": "summer_2024"
}
}Response
{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"policyVersionId": "uuid-of-policy-version",
"userReference": "user_123",
"userEmail": "user@example.com",
"consentGiven": true,
"consentHash": "a1b2c3d4e5f6...",
"ipAddress": "192.168.1.1",
"userAgent": "Mozilla/5.0...",
"metadata": {
"source": "signup_form",
"campaign": "summer_2024"
},
"createdAt": "2024-01-15T10:30:00Z"
}
}Get Consent by ID
GET /api/v1/consent/:id
{
"success": true,
"data": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"policyVersionId": "uuid-of-policy-version",
"userReference": "user_123",
"userEmail": "user@example.com",
"consentGiven": true,
"consentHash": "a1b2c3d4e5f6...",
"createdAt": "2024-01-15T10:30:00Z",
"policyDetails": {
"title": "Privacy Policy",
"type": "privacy_policy",
"version": "1.0.0"
}
}
}Get User Consents
GET /api/v1/consent/user/:userReference
{
"success": true,
"data": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"policyVersionId": "uuid-of-policy-version",
"userReference": "user_123",
"userEmail": "user@example.com",
"consentGiven": true,
"createdAt": "2024-01-15T10:30:00Z",
"policyDetails": {
"title": "Privacy Policy",
"type": "privacy_policy"
}
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"pages": 1
}
}Generate PDF Receipt
POST /api/v1/consent/:id/pdf
Generates and returns a PDF file with the consent record and cryptographic proof.
PDF Receipt Contents
- • Complete consent record details
- • SHA-256 cryptographic hash
- • Policy version information
- • Timestamp and IP address
- • QR code for verification
Get Existing PDF
GET /api/v1/consent/:id/pdf
Retrieves an existing PDF receipt if one has already been generated.
Verify Consent Hash
GET /api/v1/consent/:id/verify
Verifies the cryptographic hash of a consent record to ensure it hasn't been tampered with.
{
"success": true,
"data": {
"valid": true,
"consentId": "123e4567-e89b-12d3-a456-426614174000",
"storedHash": "a1b2c3d4e5f6...",
"computedHash": "a1b2c3d4e5f6...",
"verifiedAt": "2024-01-15T10:30:00Z"
}
}Search Consents
GET /api/v1/consent/search
Query Parameters
| Parameter | Type | Description |
|---|---|---|
| userReference | string | Filter by user reference |
| policyType | string | Filter by policy type |
| consentGiven | boolean | Filter by consent status |
| startDate | ISO date | Filter from date |
| endDate | ISO date | Filter to date |
Get Consent Statistics
GET /api/v1/consent/stats
{
"success": true,
"data": {
"totalConsents": 1250,
"acceptedConsents": 1180,
"rejectedConsents": 70,
"acceptanceRate": 94.4,
"consentsByPolicy": [
{
"policyType": "privacy_policy",
"count": 800
},
{
"policyType": "terms_of_service",
"count": 450
}
]
}
}Export Consents to CSV
GET /api/v1/consent/export
Exports consent records as a CSV file. Supports the same query parameters as the search endpoint.
Plan Requirement
CSV export requires a Starter plan or above.
Batch Record Consents
POST /api/v1/consent/batch
Record multiple consent events in a single request for improved performance.
{
"consents": [
{
"policyVersionId": "uuid-here",
"userReference": "user_123",
"userEmail": "user1@example.com",
"consentGiven": true
},
{
"policyVersionId": "uuid-here",
"userReference": "user_456",
"userEmail": "user2@example.com",
"consentGiven": true
}
]
}{
"success": true,
"data": {
"processed": 2,
"consents": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"userEmail": "user1@example.com",
"consentGiven": true
},
{
"id": "234e5678-f89b-12d3-a456-426614174001",
"userEmail": "user2@example.com",
"consentGiven": true
}
]
}
}