Generate IAB TCF consent string

To generate an IAB TCF consent string, you must implement the IAB Europe Transparency and Consent Framework policies in your CMP UI and features.

If you are collecting consents from users in the European Union, the Didomi Consents API can generate an IAB TCF consent string from the events you create for users.

To generate an IAB TCF consent string for the user, add the property $generate_tcfcs=true to the query-string parameters of the request when creating an event. The consent string will be generated and added to the consents.tcfcs property of the event response and stored in the API.

Example

POST /consents/events?organization_id={organization_id}&$generate_tcfcs=true

BODY
{
  "organization_user_id": "[e-mail]",
  "regulation": "gdpr",
  
  "consents": {
    "purposes": [
      {
        "id": "cookies",
        "enabled": true
      }
    ]
  },

  "iab": {
    "tcf": {
      "cmp_id": 7
    }
  }
}

And the response will be:

{
  ...,
  
  "consents": {
    ...,
    
    "tcfcs": "TCFv2.0+ConsentString..."
  }
}

Parameters

The generated TCF consent string can be configured with parameters passed to the iab.tcf property of the event. Those parameters must reflect how your CMP is configured to comply with the IAB TCF policies and the version of the TCF you are applying.

The fields of a TCF consent string are documented in the official IAB TCF documentation.

The following parameters can be passed to the iab.tcf property of the event:

Parameter	Description	Required	Type	Default	Notes
version	TCF version being used	No	number	2
cmp_id	The ID of the CMP that is generating the consent string.	Yes	number
cmp_version	Version of the CMP implementation.	No	number	1
consent_screen	Screen number in the CMP where consent was given.	No	number	1
consent_language	Two-letter ISO 639-1 language code in which the CMP UI was presented.	No	string	EN
vendor_list_version	Version of the IAB Global Vendor List when the user choices were collected.	No	number	81	Minimum GVL version supported is 81.
use_non_standard_texts	Indicates if non-standard texts were used in the consent notice.	No	boolean	false
purpose_one_treatment	Indicates if the purpose one was disclosed (false) or not (true).	No	boolean	false
publisher_cc	Publisher ISO 3166-1 alpha-2 country code.	No	string	AA
publisher_restrictions	Publisher restrictions that applied when the user choices were collected.	No	array	None

Example

Here is an example of an event that will generate a TCF consent string with the user's consent for the purpose cookies and some extra TCF parameters:

POST /consents/events?organization_id={organization_id}&$generate_tcfcs=true

BODY
{
  "user": {
    "organization_user_id": "[e-mail]"
  },
  "regulation": "gdpr",
  
  "consents": {
    "purposes": [
      {
        "id": "cookies",
        "enabled": true
      }
    ]
  },

  "iab": {
    "tcf": {
      "version": 2,
      "cmp_id": 7,
      "cmp_version": 1,
      "consent_screen": 1,
      "consent_language": "EN",
      "vendor_list_version": 81,
      "use_non_standard_texts": false,
      "purpose_one_treatment": false,
      "publisher_cc": "US",
      "publisher_restrictions": [
        {
          "purposeId": "cookies",
          "vendors": {
            "ids": ["google"],
            "type": "list"
          },
          "restrictionType": "disallow"
        }
      ],
    }
  }
}

Publisher restrictions

Publisher restrictions can be specified in the iab.tcf.publisher_restrictions property of the event.

Purpose IDs passed in the iab.tcf.publisher_restrictions[].purposeId property are Didomi API IDs and not IAB TCF IDs.

Vendor IDs passed in the iab.tcf.publisher_restrictions[].vendors.ids property are Didomi API IDs and not IAB TCF IDs.

Examples:

• Purpose ID cookies should be passed for IAB TCF purpose ID 1.

• Vendor ID google should be passed for IAB TCF vendor ID 755.

Example

{
  "iab": {
    "tcf": {
      "publisher_restrictions": [
        {
          "id": "restriction_1",
          "purposeId": "purpose_id",
          "vendors": {
            "ids": ["google"],
            "type": "list"
          },
          "restrictionType": "disallow"
        }
      ],
    }
  }
}

Purpose ID

The purpose ID (purposeId property) defines which purpose the publisher restriction applies to.

It must be a Didomi API purpose ID and not an IAB TCF purpose ID. For instance, use the value cookies for the IAB TCF purpose ID 1.

Vendor IDs

The vendor IDs (vendors.ids property) defines which vendors the publisher restriction applies to.

It must be a list of Didomi API vendor IDs and not IAB TCF vendor IDs. For instance, use the value google for the IAB TCF vendor ID 755.

If the restriction applies to all vendors (vendors.type is set to all), providing a list of vendor IDs is not required and will be ignored.

Vendors type

The vendors type (vendors.type property) defines how the list of vendors that the publisher restriction applies to is defined.

Must be one of:

1. list: The restriction is applied to the vendors listed in the ids property.

2. all: The restriction applies to all the vendors in the vendor list of the IAB TCF.

Restriction type

The restriction type (restrictionType property) defines how the restriction applies to the vendors.

Must be one of:

1. allow: Allow the configured vendors to process data for the purpose.

2. disallow: Prevent the configured vendors from processing data for the purpose.

3. req-consent: Require vendors to process the data for the purpose only under the consent legal basis.

4. req-li: Require vendors to process the data for the purpose only under the legitimate interest legal basis.

Purposes and vendors

The vendors and purposes fields in the consent string are automatically generated from the vendor and purpose IDs that the user has made choices for in the event (consents property).

Unsupported TCF features

The following fields will not be supported when generating a TCF string through the API:

1. DisclosedVendors