TV Consent API

Consent for Android TV, tvOS, and Roku TV apps has its own endpoint, separate from phone consent.

Tizen (Samsung TV) is captured through the web consent banner rather than the TV SDK and is documented separately — see Tizen Consent. For Android and iOS phone apps, see Mobile Consent.

Endpoints

GET /api/tvconsents

[Authentication required]

Get a page of consent records for a single Android TV, tvOS, or Roku TV application.

Records are returned newest first, ordered by LastUpdated.

Query parameters:

Parameter	Type	Description
TvAppId	string	Required. Id of the Android TV, tvOS, or Roku TV application.
FromDate	DateTime	Optional. Only return consents last updated on or after this date (UTC).
ToDate	DateTime	Optional. Only return consents last updated on or before this date (UTC, inclusive of the day).
CustomUserId	string	Optional. Only return consents whose CustomUserId starts with this value.
Status	string	Optional. One of Accepted, Declined, Partial.
Country	string	Optional. ISO 3166-1 alpha-2 code or country name.
State	string	Optional.
City	string	Optional.
ConsentId	string	Optional. Return a single record by its id.
PageNumber	integer	Optional. 1-based page number. Defaults to 1.
ResultsPerPage	integer	Optional. Defaults to 100, maximum 1000. Larger values are clamped to the maximum.
OrderBy	string	Optional. Defaults to -LastUpdated (newest first). Prefix with - for descending.

A TvAppId that does not match an application on your account returns 403 Forbidden. A phone or Tizen application id returns 400 Bad Request naming the endpoint to use instead.

Example request:

curl -G "https://api-prod.secureprivacy.ai/api/tvconsents" \
  -H "Authorization: Bearer {token}" \
  -d "TvAppId=64b2f0a1c3d4e5f6a7b8c9d3" \
  -d "FromDate=2026-01-01"

Response: 200 OK

{
  "PagedResults": [
    {
      "ConsentId": "string",
      "ClientId": "string",
      "CustomUserId": "string",
      "TvAppId": "string",
      "ScreenUri": "string",
      "ConsentGiven": "string",
      "Created": "string",
      "LastUpdated": "string",
      "Expiration": "string",
      "Categories": [
        {
          "Category": "string",
          "ConsentGiven": "string",
          "Packages": [
            {
              "PackageName": "string",
              "PackageId": "string",
              "IsEnabled": "boolean"
            }
          ]
        }
      ],
      "IabConsents": [
        {
          "Name": "string",
          "Id": "integer",
          "ConsentGiven": "boolean",
          "ConsentType": "string"
        }
      ],
      "Device": {
        "City": "string",
        "State": "string",
        "Country": "string",
        "DeviceManufacturer": "string",
        "OsVersion": "string",
        "SdkVersion": "string"
      }
    }
  ],
  "TotalResultsCount": "integer"
}

Field reference:

Field	Description
TotalResultsCount	Number of records matching your filters across all pages.
ConsentId	Unique id of the stored consent record.
CustomUserId	Your own user identifier, when one was linked to the consent.
ScreenUri	Screen the consent was captured on.
ConsentGiven	Overall outcome: All, Partial or None.
LastUpdated	When the consent was last updated (UTC). This is the field filtered by FromDate / ToDate.
Expiration	When the record is due to be purged under the applied data retention period (UTC).
Categories	Per-category decisions. Category is the compliance category (e.g. Essential, Analytics), ConsentGiven is All, Partial or None, and Packages lists the SDK packages in that category with whether each was allowed.
IabConsents	IAB TCF consents, when the banner is running in IAB mode.
Device	Device and location context. Directly identifying device data is not exposed by this API.

Android TV, tvOS, and Roku TV consent is written by the same SDK as phone consent, so this record matches the Mobile Consent record field for field, apart from TvAppId in place of MobileApplicationId. It has its own endpoint so that the two can diverge without breaking either.

Paging through a full extract:

Keep requesting pages until you have read TotalResultsCount records:

Node.js

const perPage = 1000;
let page = 1;
let total = Infinity;
const all = [];

while (all.length < total) {
  const res = await fetch(
    `https://api-prod.secureprivacy.ai/api/tvconsents?TvAppId=${appId}&PageNumber=${page}&ResultsPerPage=${perPage}`,
    { headers: { Authorization: `Bearer ${token}` } }
  );

  const body = await res.json();
  total = body.TotalResultsCount;
  all.push(...body.PagedResults);
  page++;
}

Because consents are updated as users change their preferences, a record can move between pages while you are reading. For a stable extract, pin the window with FromDate and ToDate and page within it, then run a smaller incremental job for the most recent period. For large extracts, see the Rate Limits documentation.

For Tizen (Samsung TV) apps, see Tizen Consent. For phone apps, see Mobile Consent.