Consent

Two groups of endpoints handle consent: the unversioned ingestion endpoint that the banner runtime posts to when a visitor makes a choice, and key-authenticated endpoints that read and write a subject's consent state across devices.

How the banner records a consent choice

POST /api/consent/log

This unversioned route is what the generated banner script calls. It is not part of the key-authenticated v1 API: requests carry no API key, are rate limited per client IP (1,000 requests per minute), and are accepted cross-origin so the banner can post from your domain. Each request is validated against the banner's authorized domain list — a post from a domain the banner is not configured for is rejected with HTTP 403.

The payload uses the public Banner ID (the one in the loader script URL), a preferences object of category booleans, a method (consent_given, consent_changed, consent_default, accept_all, or accept_necessary), and an ISO 8601 timestamp. Optional fields cover geo resolution (country, region, matchedRuleId), the privacy signal detected at choice time, and US opt-out purposeChoices.

Server-side, the route resolves the public ID to the banner, clamps implausible client timestamps, and stores a privacy-minimized record: raw IP and user agent are never written, and the referrer is redacted to the banner's configured telemetry level. A successful write returns HTTP 200 with success: true, the stored consentLogId, and — for explicit visitor choices — a short-lived managePreferences URL the banner can offer for later changes. Explicit choices also trigger the consent.given webhook event; machine-written default-state rows do not.

You normally never call this route yourself — the published banner script handles it, including the exact payload shape, which evolves with the runtime. It is documented here so you can recognize and troubleshoot the banner's network traffic.

Cross-device consent state

The subject endpoints store a visitor's consent state server-side so it can follow them across devices. They identify a subject by three fields, sent in every request body:

Request bodies are limited to 20 KB. These endpoints require a plan that includes cross-device consent; other plans receive a plan_required error (HTTP 403).

Read a subject's state

POST /api/v1/consent/subjects/resolve

Requires the consent:read scope.

{
  "bannerId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "namespace": "default",
  "subjectId": "account-81f3c2"
}

Returns the stored snapshot, or found: false when none exists:

{
  "data": {
    "found": true,
    "consentState": { "schemaVersion": 2, "categories": ["necessary", "analytics"] },
    "protocolVersion": 1,
    "version": 3,
    "clientUpdatedAt": "2026-08-13T11:58:00.000Z",
    "updatedAt": "2026-08-13T11:58:01.000Z",
    "expiresAt": "2026-11-13T11:58:01.000Z"
  },
  "version": "v1"
}

Write a subject's state

PUT /api/v1/consent/subjects/state

Requires the consent:write scope and a live key. The body adds three fields to the subject reference:

The canonical consentState object:

A successful write returns HTTP 200 with success: true plus the stored snapshot in the same shape as the resolve response.

If baseVersion does not match the stored version, the write is rejected with HTTP 409 and the code version_conflict; the response includes the current snapshot so you can merge and retry:

{
  "data": {
    "error": "Consent version conflict",
    "code": "version_conflict",
    "current": {
      "consentState": { "schemaVersion": 2, "categories": ["necessary"] },
      "protocolVersion": 1,
      "version": 4,
      "clientUpdatedAt": "2026-08-13T11:59:00.000Z",
      "updatedAt": "2026-08-13T11:59:01.000Z",
      "expiresAt": "2026-11-13T11:59:01.000Z"
    }
  },
  "version": "v1"
}

Delete a subject's state

DELETE /api/v1/consent/subjects/state

Requires the consent:write scope and a live key. Send only the subject reference fields (bannerId, namespace, subjectId). The response reports how many records were deleted:

{
  "data": {
    "success": true,
    "deleted": 1
  },
  "version": "v1"
}

Use this to honor a visitor's request to forget their stored consent state.

Subject endpoint errors