API Reference

Integrate with the Conzent Consent Management Platform. These endpoints power the consent banner, geolocation targeting, consent audit logging, and cookie scanning.

All endpoints are relative to your self-hosted Conzent instance. Replace the base URL with your actual domain.

Authentication

Most endpoints are public — they are called from the consent banner script running on your visitors' browsers.

Endpoints that accept data use a Website Key to identify which site the request belongs to. Find your website key in the Conzent dashboard under Sites.

Response Format

API responses use two formats depending on the endpoint:

Standard Response

Used by Health Check and Scan Webhook.

{
  "success": true,
  "data": {
    "status": "ok"
  }
}

Lightweight Response

Used by beacon endpoints (Pageview, Consent, Scan Data) for minimal overhead.

{
  "status": "ok"
}

Health Check

Returns the health status of the application and backing services. Use for monitoring, load balancer checks, and Docker healthcheck probes.

Response

{
  "success": true,
  "data": {
    "status": "ok",
    "services": {
      "database": true,
      "redis": true
    },
    "environment": "production",
    "timestamp": "2026-03-16T12:00:00+00:00"
  }
}

{
  "success": true,
  "data": {
    "status": "degraded",
    "services": {
      "database": true,
      "redis": false
    }
  }
}

Example

curl https://your-instance.example.com/health

Geolocation

Returns the visitor's country code and EU membership status. Used by the consent script to apply geo-targeted regulations (GDPR, CCPA).

Response Fields

Response

{
  "country": "dk",
  "in_eu": true
}

Example

curl https://your-instance.example.com/api/v1/geo_ip

Pageview Beacon

Records pageview and banner-load events. Sent via navigator.sendBeacon() as multipart/form-data. Increments the daily pageview counter and buffers cookie observations for async processing.

Request Body multipart/form-data

Response

{
  "status": "ok"
}

Example

curl -X POST https://your-instance.example.com/api/v1/log \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "request_type=banner_load" \
  -F "log_time=$(date +%s)"

Consent Log

Records the GDPR consent audit trail when a visitor accepts, rejects, or customises consent. This is the primary compliance endpoint.

Request Body multipart/form-data

Response

{
  "status": "ok"
}

Example

curl -X POST https://your-instance.example.com/api/v1/consent \
  -F "key=YOUR_WEBSITE_KEY" \
  -F "conzent_id=a1b2c3d4e5f6..." \
  -F 'log=[{"category":"analytics","consented":true}]' \
  -F "consented_domain=example.com" \
  -F "language=en" \
  -F "country=dk"

Scan Data Beacon

Receives client-side cookie scan data. The consent script detects cookies on the visitor's browser and reports them for automatic categorisation. Data is buffered in Redis and processed asynchronously.

Request Body multipart/form-data

Payload Structure

{
  "scan_id": 123,
  "action": "runscan",
  "scan_url": "https://example.com/",
  "consent_phase": "pre_consent",
  "data": {
    "cookies": [
      { "name": "_ga", "domain": ".example.com" }
    ]
  }
}

Response

{
  "status": "ok"
}

Example

curl -X POST https://your-instance.example.com/api/v1/scan_data \
  -F "key=YOUR_WEBSITE_KEY" \
  -F 'payload={"scan_id":123,"action":"runscan","scan_url":"https://example.com/"}'

Scanner Webhook

Receives scan results from external scanner servers when a cookie scan completes. Authenticated via X-Api-Key header matching the SCANNER_WEBHOOK_SECRET environment variable.

Headers

Request Body application/json

Response

{
  "success": true,
  "data": {
    "status": "processed"
  }
}

Error

{
  "success": false,
  "error": "Unauthorized"
}

Example

curl -X POST https://your-instance.example.com/api/v1/scan-webhook \
  -H "X-Api-Key: YOUR_SCANNER_WEBHOOK_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "webhook",
    "scan_id": 456,
    "scan_url": "https://example.com/",
    "data": {
      "cookies": [
        {"name": "_ga", "domain": ".example.com", "category": "analytics"}
      ]
    }
  }'