Developers Guide

Integrate the POPIASAFE compliance platform using Public API v1 and webhook events with predictable auth, quota, and error responses.

Open Developers SettingsAdmin only

View Supported Integrations

Public API v1 quick start

Base path: /api/v1. Auth header: Authorization: Bearer psk_<your-key>.

List consent forms

curl -s -X GET "https://api.popiasafe.com/api/v1/consent-forms?page=1&pageSize=20" \
  -H "Authorization: Bearer psk_YOUR_API_KEY" \
  -H "Accept: application/json"

Get a single consent form

curl -s -X GET "https://api.popiasafe.com/api/v1/consent-forms/{id}" \
  -H "Authorization: Bearer psk_YOUR_API_KEY"

Create consent record

curl -s -X POST "https://api.popiasafe.com/api/v1/consent-records" \
  -H "Authorization: Bearer psk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"consentFormId":"00000000-0000-0000-0000-000000000000","contactEmail":"person@example.com"}'

Response examples

Success (200)

{
  "success": true,
  "data": { "items": [], "totalCount": 0, "page": 1, "pageSize": 20 },
  "requestId": "req_123"
}

Unauthorized (401)

{
  "success": false,
  "error": { "code": "INVALID_API_KEY", "message": "Missing or invalid API key." },
  "requestId": "req_401",
  "timestamp": "2026-03-03T10:00:00Z"
}

Quota exceeded (429)

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "API request limit exceeded.",
    "details": { "retryAfterSeconds": 3600 }
  },
  "requestId": "req_429",
  "timestamp": "2026-03-03T10:00:00Z"
}

Common mistakes

Wrong: https://api.popiasafe.com/v1/consent-forms | Right: https://api.popiasafe.com/api/v1/consent-forms
Wrong: Api-Key: psk_... | Right: Authorization: Bearer psk_...
Wrong: POST /api/v1/consent-forms | Right: use GET for forms and POST /api/v1/consent-records to create records

Webhooks

Configure webhook endpoints in Settings → Developers and verify signatures on every delivery.

X-PopiaSafe-Signature: <hex hmac-sha256>
X-PopiaSafe-Timestamp: <unix-seconds>