Consent Verification API

Verify visitor consent status server-side before sending events to Google, Meta, or any other server-side analytics or advertising platform.

Why server-side consent verification?

When you fire events from your server (e.g., via server-side Google Tag Manager or Meta Conversions API), the browser’s consent state isn’t available. You need a way to check whether a visitor actually consented before sending their data to third-party services.

The Consent Verification API lets you query CookieBoss for a visitor’s current consent status in real time.

Common use cases

• Server-side Google Tag Manager (sGTM) — check consent before forwarding events from your tagging server
• Meta Conversions API (CAPI) — only send purchase or lead events for visitors who consented to marketing
• Server-side analytics — validate consent before logging events to your data warehouse
• Ad conversion tracking — ensure you only report conversions from consented users

Authentication

All requests require an API key passed via the X-API-Key header. You can generate API keys in the dashboard under Settings > API Keys.

Endpoint

{
"hasConsent": true,
"categories": {
  "necessary": true,
  "analytics": true,
  "marketing": false,
  "functional": true
},
"consentedAt": "2026-03-08T12:00:00Z",
"geoCountry": "DE"
}

Parameters

Response when no consent is found

If the visitor hasn’t interacted with the consent banner yet, or if the visitor ID is invalid:

{
"hasConsent": false,
"categories": null,
"consentedAt": null,
"geoCountry": null
}

Rate limits

Requests exceeding the rate limit receive a 429 Too Many Requests response. The Retry-After header indicates how many seconds to wait before retrying.

Integration example

Here’s a Node.js example that checks consent before sending a server-side conversion event:

const response = await fetch(
`https://api.cookieboss.io/api/v1/public/sites/${siteId}/consent/verify?visitor_id=${visitorId}`,
{ headers: { 'X-API-Key': process.env.COOKIEBOSS_API_KEY } }
);
const { hasConsent, categories } = await response.json();

if (hasConsent && categories?.marketing) {
// Safe to fire marketing tags server-side
await sendConversionEvent(visitorId, eventData);
}

Step by step

1. Capture the visitor ID on the client. When a user triggers an event (e.g., a purchase), read their visitor ID:

   const visitorId = __cookieboss.getVisitorId();

2. Send the visitor ID to your server along with the event data (e.g., in a form submission, AJAX call, or webhook payload).
3. Call the Consent Verification API from your server before forwarding the event to third parties.
4. Check the relevant category. Use categories.marketing for ad conversions, categories.analytics for analytics events, etc.
5. Only fire the server-side tag if the visitor has consented to the relevant category.

sGTM integration

If you’re using server-side Google Tag Manager, you can call the Consent Verification API from a custom variable or client template:

const sendHttpGet = require('sendHttpGet');

const siteId = 'YOUR_SITE_ID';
const visitorId = data.visitorId; // passed from the client container
const apiKey = data.apiKey;

const url = 'https://api.cookieboss.io/api/v1/public/sites/' + siteId + '/consent/verify?visitor_id=' + visitorId;

sendHttpGet(url, {
headers: { 'X-API-Key': apiKey }
}).then((result) => {
const body = JSON.parse(result.body);
return body.hasConsent && body.categories && body.categories.marketing;
});