Capture · REST API

The Capture REST API can also be used directly without using the JavaScript framework. The actual endpoint to use will be configured by Onesecondbefore.

This REST API endpoint can be used to store consent given by a user. There are two different versions depending on whether you know the TCF 2.0 consent string or not and whether you would like to retrieve one if it's unknown.

Request · TCString known:

POST /consent HTTP/1.1
Host: ${ENDPOINT}
Content-Type: application/json; charset=utf-8

{
    "aid": "...",
    "sid": "...",
    "ns": "...",
    "url": "...",
    "cduid": "...",
    "consent": "...",
    "tcstring": "...",
    "version": "..."
}

Request · TCString not known:

POST /consent?iab=1 HTTP/1.1
Host: ${ENDPOINT}
Content-Type: application/json; charset=utf-8

{
    "aid": "...",
    "sid": "...",
    "ns": "...",
    "url": "...",
    "consent": "...",
    "cduid": "...",
    "version": "..."
}

Request parameters

nametyperequireddescription
aidJSON payloadYesAccount id, similar to the one used in the JavaScript library.
sidJSON payloadNoSite id, similar to the one used in the JavaScript library, default "development".
nsJSON payloadNoNamespace, similar to the one used in the JavaScript library.
urlJSON payloadYesThe URL for which this consent applies. For mobile apps this might be the unique app identifier.
consentJSON payloadYesThe consent string in a human readable format (if no tcstring is specified):
  • "none" - no consent is given
  • "all" - all consents are given
  • "comma separated list of names" - a comma separated list of purpose names like "social,analytics,marketing"; these will not be translated into any known purposes if ?iab=1 is specified as well.
  • "comma separated purpose id's" - a list of purposes, like "2,7,9".
cduidJSON payloadNoThe unique identifier of the user, either IDFA / IDFV (for iOS), AAID (for Android). If not specified one will be generated in the response which should be stored and used subsequently, if necessary.
versionJSON payloadNoThe version of the consent that the user consented to. Used to distinguish different versions of the consents that were shown to the user, default 1.
tcstringJSON payloadNoIf an IAB TCF string is known, this will be used to store consent rather than the consent payload variable.
iabQuery stringNoIf no tcstring is specified in the input and an encoded version based upon the specified consent payload variable is required, add the querystring parameter ?iab=1

Response payload

The response is in JSON format.

Content-Type: application/json; charset=utf-8

{
    "cduid": "${CROSS_DOMAIN_USER_ID}",
    "consent": "${CONSENT}",
    "tcstring": "${TCSTRING}"
}

Response parameters

namedescription
cduidThe cross-domain user-id (IDFA / IDFV for iOS, AAID for Android) if specified in the request, or a newly generated one if not specified. Value should be stored locally (in the app) for subsequent use.
consentThe consent as given in the payload request
tcstringThe tcstring as either given in the payload request, or calculated based upon the consent JSON payload input when ?iab=1 is specified in the request.

Examples

Consent "all"

POST /consent HTTP/1.1
Host: privacy.example.com
Content-Type: application/json; charset=utf-8

{
    "aid": "cmp",
    "sid": "example-web",
    "ns": null,
    "url": "https://www.example.com",
    "consent": "all",
    "tcstring": "AAAAAAAAAAAAFjAAAENAAAAAP_AAP_AACiQAAAAAAAA",
    "cduid": "983f52a9-3ba1-4acb-86c0-f8f311d69adf",
    "version": 1
}
Content-Type: application/json; charset=utf-8

{
    "consent": "all",
    "cduid": "983f52a9-3ba1-4acb-86c0-f8f311d69adf"
}

Consent "none"

POST /consent HTTP/1.1
Host: privacy.example.com
Content-Type: application/json; charset=utf-8

{
    "aid": "cmp",
    "sid": "example-web",
    "ns": null,
    "url": "https://www.example.com",
    "consent": "none",
    "cduid": "983f52a9-3ba1-4acb-86c0-f8f311d69adf",
    "version": 1
}
Content-Type: application/json; charset=utf-8

{
    "consent": "none",
    "cduid": "not-accepted"
}

Include IAB TCString in response for purposes 2, 7 and 9. No cduid in request

POST /consent?iab=1 HTTP/1.1
Host: privacy.example.com
Content-Type: application/json; charset=utf-8

{
    "aid": "cmp",
    "sid": "example-app",
    "url": "https://example.app",
    "consent": "2,7,9"
}
Content-Type: application/json; charset=utf-8

{
    "consent": "2,7,9",
    "cduid": "1c27f400-d90b-4577-a27d-c7dcdab22431",
    "tcstring": "CAAAAAAAAAAAAFjABBNLAACgAEKAAEKAABpYAAAAAAAA"
}