Record consent

POST/v1/consent

Projects using wavebird_consent require a current stored consent record for the authenticated tenant, client_id, and session_id. Record the actual user decision through /v1/consent before placement; inline flags cannot replace or expand that permission. Other project modes may accept request-level flags; they do not bypass origin, protocol, GPC, or activation gates.

AUTH

Secret key, or activation token for browser flows

CONTENT TYPE

application/json

STATUS

Contract may change
Secret key or browser activation tokenVerification stepsOpen as Markdown ↗

Request parameters

client_id
string
Required
Project ID (client_id, WAVEBIRD_CLIENT_ID), formatted like wbproj_....
session_id
string
Required
Publisher session identifier.
decision
string
Required
Consent decision: personalized, basic, or custom.
source
string
Required
Consent source: publisher_custom, server_sync, or wavebird_dialog. Compatibility aliases publisher and custom_dialog normalize to publisher_custom but are not recommended for new integrations.
lifecycle_state
string
Optional
Explicit session state: granted, denied, withdrawn, revoked, or cmp_error. Omission retains an existing state; it does not reopen a withdrawn record. For synthetic staff Test sessions, record an explicitly scoped test authorization.
revision
integer
Optional
Positive state revision. Omission allocates the next revision; when supplied, stale or conflicting updates are rejected. Use a newer explicit granted state only after a fresh authorization decision.
purposes
object
Optional
Purpose-level consent flags: semantic_targeting, session_persistence, cross_session_persistence, and prompt_shared. Compatibility purposes.ads maps to semantic_targeting and purposes.measurement maps to session_persistence.

Returns

consent_id
string
Stored consent record identifier.
session_id
string
Publisher session identifier for the stored consent state.
expires_at
string
ISO timestamp when the stored consent state expires.
authoritative_consent
object
Complete stored lifecycle snapshot: optional consent_id, lifecycle_state, revision, update and expiry timestamps, source, and purposes.
normalized.source
string
Canonical source after compatibility alias mapping.
normalized.purposes
object
Canonical purpose flags after compatibility ads/measurement mapping.

Integration guidance

Placement consent vs /v1/consent sync

Projects using wavebird_consent require a current stored consent record for the authenticated tenant, client_id, and session_id. Record the actual user decision through /v1/consent before placement; inline flags cannot replace or expand that permission.

Only synchronize a decision actually obtained for this session and its purposes. A documentation example is not consent. TCF and GPP inputs are currently rejected at admission with validation_error (400), including structurally valid strings, because an authoritative vendor, purpose, and jurisdiction policy mapping is not configured. Do not interpret field support as permission to deliver ads. An observed positive Sec-GPC signal blocks new advertising admission with privacy_signal_policy_required (403). Preserve the signal across backend requests and keep the primary application flow available; do not retry by removing the signal.

On withdrawal, synchronize lifecycle_state: withdrawn with a newer revision for the same authenticated project and session. Subsequent placements fail closed with consent_not_current (403). Replaying an older grant returns consent_state_conflict (409); inline placement flags cannot restore authorization. Missing, expired, invalid, foreign-scope or unavailable stored authorization also denies advertising while the primary application remains available.

Consent pathLocationPurposeRequired before placement
Request-level placement consentinside /v1/placementsper-request privacy and targeting signalDoes not replace required stored consent
Consent sync/v1/consentsession-level publisher consent stateRequired for wavebird_consent projects

Canonical /v1/consent sync body and compatibility aliases

This body illustrates a recorded decision. Replace its purpose flags with the actual session decision; never grant permission merely to make a placement succeed.

Compatibility aliases remain supported after the canonical form: source: "publisher" normalizes to publisher_custom, purposes.ads maps to semantic_targeting, and purposes.measurement maps to session_persistence.

{
  "client_id": "wbproj_...",
  "session_id": "sess_...",
  "decision": "custom",
  "source": "publisher_custom",
  "purposes": {
    "semantic_targeting": false,
    "session_persistence": true,
    "cross_session_persistence": false,
    "prompt_shared": false
  }
}

Errors

unauthorized401

Missing auth.

forbidden403

Publishable key origin is not allowed, or raw publishable-key auth was used instead of a browser activation token.

validation_error400

Consent purposes are missing or malformed.

consent_state_conflict409

A stale lifecycle revision cannot replace the current session state.

consent_state_invalid409

The lifecycle transition or stored scope is invalid.

Related

Need help with your integration?

Share the affected endpoint, request ID, and the behavior you expected. Leave out keys and user content.

Contact the team