Record consent

POST/v1/consent

Optional session/user-level consent sync. It is separate from request-level placement consent and is not required before /v1/placements when that request already carries consent flags.

AUTH

Secret key, or activation token for browser flows

CONTENT TYPE

application/json

STATUS

Contract may change

Secret key or browser activation tokenSandbox this Open 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.

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.

Name	Type	Required	Description
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.
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.

Name	Type	Description
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

Request-level placement consent is sent inside /v1/placements and controls per-request privacy and targeting behavior. It is not required to call /v1/consent first when the placement request already carries request-level consent.

/v1/consent is optional session/user-level consent sync for external CMP or publisher consent state.

Consent path	Location	Purpose	Required before placement
Request-level placement consent	inside /v1/placements	per-request privacy and targeting signal	No
Consent sync	/v1/consent	session/user-level CMP or publisher consent state	Optional

Canonical /v1/consent sync body and compatibility aliases

New integrations should use this canonical /v1/consent sync body when syncing session/user-level CMP or publisher consent state.

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

CODESTATUSWHEN IT HAPPENS

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.

API v1 overview Testing in sandbox Errors