IAB TCF v2.2 implementer quick reference

What this is

The IAB Transparency and Consent Framework (TCF) v2.2 exposes one in-page function, __tcfapi, through which tags read a user’s consent and legitimate-interest signals from a Consent Management Platform (CMP). This card lists its commands, return objects, enum values, the Global Vendor List purpose set, and the v2.2 behavior changes that break integrations written for older versions.

The interface

__tcfapi(command, version, callback, parameter)

window.__tcfapi must always be a function — including while only the stub is in place during init — never any other type. version is the API major version, which is 2 for all of TCF v2.x. parameter is command-specific and often omitted.

Commands

Only getTCData is deprecated. getInAppTCData and getVendorList remain current optional commands.

PingReturn fields

Status enums

cmpStatus (in PingReturn and TCData):

displayStatus (in PingReturn):

eventStatus (delivered to addEventListener callbacks):

Gate new consent-dependent processing on useractioncomplete. Use tcloaded only to honor an already-stored valid TC String, and handle cmpuishown by waiting for the user to confirm.

TCData object (when GDPR applies)

When GDPR does not apply, only gdprApplies, tcfPolicyVersion, cmpId and cmpVersion exist on the object — tcString and the purpose/vendor maps are absent by spec. Reading them without branching on gdprApplies throws or returns undefined.

The success boolean

Purposes (11)

Special purposes, features, special features

Special feature opt-ins are surfaced through specialFeatureOptins in TCData.

Legal-basis matrix (v2.2 change)

TCF v2.2 removed legitimate interest as an acceptable legal basis for the profiling and personalisation purposes. For these, evaluate purpose.consents only; ignore purpose.legitimateInterests.

Version numbers (do not confuse them)

Do not hardcode tcfPolicyVersion === 4. The TC String Version field (2) is a different number from tcfPolicyVersion (4 or 5).

Global Vendor List (v3) endpoints

The GVL JSON contains: gvlSpecificationVersion, vendorListVersion, tcfPolicyVersion, lastUpdated, purposes, specialPurposes, features, specialFeatures, stacks, dataCategories, and vendors.

Stub detection and cross-frame calls

Check for window.__tcfapi. For cross-frame access, locate an ancestor frame that has a child frame named __tcfapiLocator. The stub queues calls, creates the __tcfapiLocator iframe, and installs a postMessage handler; ping’s cmpLoaded / cmpStatus tell you whether the real CMP has replaced it.

// request
{ __tcfapiCall: { command, parameter, version, callId } }
// response
{ __tcfapiReturn: { returnValue, success, callId } }

callId is a unique id chosen by the caller to correlate the response.

First-layer UI requirements (v2.2)

Certified v2.2 CMPs must disclose, on the first layer of the UI, the number of third-party vendors seeking consent, and must make available standardized illustrations (based on real use cases) explaining how participants’ data processing relates to the purposes. Adopting a certified v2.2 CMP inherits these rather than coding them.

Gotchas

1. getTCData returns nothing, or your CMP does not implement it. Cause: it was deprecated in v2.2 (May 2023) and is optional; only ping, addEventListener, removeEventListener are required. Fix: register an addEventListener callback and read tcData from it (it fires immediately with current data).
2. tcData.tcString or purpose.consents is undefined for some users. Cause: when GDPR does not apply, the object holds only gdprApplies, tcfPolicyVersion, cmpId, cmpVersion. Fix: branch on gdprApplies first and never assume tcString exists.
3. __tcfapi(...) calls are silently dropped on early page load. Cause: only the stub is active (cmpStatus stub, cmpLoaded false); the CMP decision is not ready. Fix: use addEventListener and wait for tcloaded or useractioncomplete, or poll ping until cmpLoaded / loaded.
4. Pixels fire before the user actually chose. Cause: tcloaded means a valid (possibly pre-existing) TC String is available, not that the user interacted this session. Fix: gate new processing on useractioncomplete; use tcloaded only to honor a stored string.
5. A tcfPolicyVersion === 4 check starts rejecting valid v2.2 strings. Cause: the policy was incremented to 5 (effective 4 Oct 2024); both 4 and 5 are v2.2. Fix: detect with ping.tcfPolicyVersion >= 4; treat policy < 4 strings as invalid.
6. An addEventListener callback keeps firing and leaks. Cause: it is re-invoked on every TC String change until explicitly removed. Fix: capture tcData.listenerId and call removeEventListener with it (store the id and remove on a later tick — removing from inside the callback is not documented as safe).
7. Personalised-ads vendors are wrongly allowed via legitimate interest. Cause: v2.2 removed LI as a legal basis for Purposes 3, 4, 5, 6. Fix: for Purposes 3–6 evaluate purpose.consents only; honor LI only for Purposes 2, 7, 8, 9, 10, 11 where declared.
8. Server-side GVL fetch is rate-limited or serves stale data. Cause: not caching per the response max-age; unversioned latest changes under you. Fix: cache exactly as a browser would, and pin a versioned archive matching the VendorListVersion in the TC String for reproducibility.

Quick recipes

// Wait for a usable consent state, then act. Works whether the CMP is still a
// stub or already loaded — the callback fires immediately with current data.
window.__tcfapi('addEventListener', 2, function (tcData, success) {
  if (!success) return;                        // registration failed
  if (tcData.gdprApplies === false) {          // reduced object, no tcString
    startTags();                               // GDPR out of scope here
    return;
  }
  if (tcData.eventStatus === 'useractioncomplete' ||
      tcData.eventStatus === 'tcloaded') {
    applyConsent(tcData);                       // honor the TC String
    var listenerId = tcData.listenerId;         // capture id; remove on a later tick
    setTimeout(function () {                     // (spec does not document in-callback removal)
      window.__tcfapi('removeEventListener', 2, function () {}, listenerId);
    }, 0);
  }
  // 'cmpuishown' => UI is showing; wait for the user to confirm.
});

// Purposes 3 & 4 are consent-only in v2.2 — do not read legitimateInterests.
const MY_VENDOR_ID = 755; // replace with your IAB-assigned vendor id
function canRunPersonalisedAds(tcData) {
  const p = tcData.purpose.consents;
  const v = tcData.vendor.consents;
  return Boolean(p[1] && p[3] && p[4] && v[MY_VENDOR_ID]);
}

// tcfPolicyVersion is the pragmatic 'am I on v2.2?' probe.
window.__tcfapi('ping', 2, function (ping) {
  const ready = ping.cmpLoaded && ping.cmpStatus === 'loaded';
  const isV22 = typeof ping.tcfPolicyVersion === 'number' &&
                ping.tcfPolicyVersion >= 4;    // 4 or 5 are both v2.2
  console.log({ ready, isV22, policy: ping.tcfPolicyVersion });
});

// Call __tcfapi from a frame that does not host the CMP.
function callTcf(command, version, parameter, cb) {
  const callId = String(Math.random());
  function onMessage(event) {
    let payload = event.data;
    if (typeof payload === 'string') {
      try { payload = JSON.parse(payload); } catch (e) { return; }
    }
    const r = payload && payload.__tcfapiReturn;
    if (r && r.callId === callId) {
      window.removeEventListener('message', onMessage);
      cb(r.returnValue, r.success);
    }
  }
  window.addEventListener('message', onMessage);
  // Post to the frame owning the '__tcfapiLocator' child frame:
  window.top.postMessage({ __tcfapiCall: { command, parameter, version, callId } }, '*');
}
callTcf('ping', 2, undefined, function (returnValue) { console.log(returnValue); });

// Prefer 'latest' with browser-style caching; pin an archive for reproducibility.
async function getGvl(vendorListVersion) {
  const base = 'https://vendor-list.consensu.org/v3';
  const url = vendorListVersion
    ? `${base}/archives/vendor-list-v${vendorListVersion}.json`
    : `${base}/vendor-list.json`;
  const res = await fetch(url);                 // honor the response max-age
  return res.json();                             // { purposes, vendors, tcfPolicyVersion, ... }
}

Related

• Hub: Privacy and consent guides
• Consent Mode v2 reference · GA4 Measurement Protocol reference

Sources

Official pages these values were read from (read 2026-07-20):

• IAB Tech Lab — CMP API v2 (TCF v2.2 technical spec) (read 2026-07-20)
• IAB Tech Lab — Consent string and vendor list formats v2 (read 2026-07-20)
• TCF v2.2 Global Vendor List (live GVL v3 JSON) (read 2026-07-20)
• Understanding the Transparency and Consent Framework v2.2 — IAB Europe (read 2026-07-20)
• FAQ: TCF v2.2 (updated November 2023) — IAB Europe (PDF) (read 2026-07-20)

Honesty notes. gvlSpecificationVersion (3), vendorListVersion (168) and tcfPolicyVersion (5) are point-in-time values read from the live GVL on the verification date — vendorListVersion increments roughly weekly, so verify against the live GVL at build time rather than hardcoding. The publisher.restrictions value meanings (0, 1, 2 as restriction types) and the statement that Purpose 1 is consent-only reflect known TCF semantics; re-confirm the exact restriction-type enumeration against the consent-string format spec before relying on it. The spec does not explicitly state whether removeEventListener may be called from inside the addEventListener callback, so this card removes on a later tick. The loading cmpStatus is documented as deprecated but has no stated removal version, so some CMPs may still emit it.