Record consent
/v1/consentPREVIEWOptional 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
CONTENT TYPE
STATUS
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.
- 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. |
| 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
unauthorized401Missing auth.
forbidden403Publishable key origin is not allowed, or raw publishable-key auth was used instead of a browser activation token.
validation_error400Consent purposes are missing or malformed.