Web Consent API

Endpoints

GET /api/consents

[Authentication required]

Get a page of consent records for a single domain. Use this to extract many consents at once, rather than polling GET /api/consent/:clientId one client id at a time.

Records are returned newest first, ordered by LastUpdated.

Query parameters:

Parameter	Type	Description
DomainId	string	Required. Id of the domain. A domain URL is also accepted.
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 DomainId that does not match a domain on your account returns 403 Forbidden.

Example request:

curl -G "https://api-prod.secureprivacy.ai/api/consents" \
  -H "Authorization: Bearer {token}" \
  -d "DomainId=64b2f0a1c3d4e5f6a7b8c9d0" \
  -d "FromDate=2026-01-01" \
  -d "ResultsPerPage=250"

Response: 200 OK

{
  "PagedResults": [
    {
      "ConsentId": "string",
      "ClientId": "string",
      "CustomUserId": "string",
      "DomainId": "string",
      "PageUrl": "string",
      "Status": "string",
      "Created": "string",
      "LastUpdated": "string",
      "Expiration": "string",
      "Categories": [
        {
          "Category": "string",
          "CategoryId": "string",
          "ConsentGiven": "boolean",
          "Services": [
            {
              "Name": "string",
              "IsEnabled": "boolean"
            }
          ]
        }
      ],
      "IabConsents": [
        {
          "Name": "string",
          "Id": "integer",
          "ConsentGiven": "boolean",
          "ConsentType": "string"
        }
      ],
      "BrowserSignals": {
        "GPC": "boolean",
        "DNT": "boolean"
      },
      "Device": {
        "Browser": "string",
        "City": "string",
        "State": "string",
        "Country": "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.
PageUrl	URL of the page the consent was captured on.
Status	Overall outcome: Accepted, Declined or Partial.
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. ConsentGiven is a boolean — the web banner records one decision per category — and Services lists the individual services in that category, each with a Name and whether it was allowed.
IabConsents	IAB TCF consents, when the banner is running in IAB mode.
BrowserSignals	GPC and DNT signals captured at consent time.
Device	Browser and location context. Directly identifying device data is not exposed by this API.

This record is shaped for web. The mobile equivalent is deliberately different — a mobile category carries a tri-state decision over named SDK packages rather than a boolean over services — so parse the two separately.

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/consents?DomainId=${domainId}&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.

To extract consents for a mobile or TV app, see GET /api/mobileconsents.

GET /api/consent/:clientId

Get the full consent record for a user.

Request:

{
  "Domain": "string"
}

Response:

{
  "ClientId": "string",
  "ComplianceType": "string",
  "ConsentGiven": "boolean",
  "ComplianceTypeID": "string",
  "PluginPreferences": "string",
  "PageURL": "string",
  "IabConsent": {
    "Name": "string",
    "Id": "integer",
    "ConsentGiven": "boolean",
    "ConsentType": "string"
  }
}

GET /api/consent/customuserid/:clientId

Get the consent record for a user with CustomUserId inlcuded.

[Authentication required]

Request:

{
  "DomainId": "string"
}

Response:

{
  "ClientId": "string",
  "CustomUserId": "string",
  "PageURL": "string",
  "Consents": [
    {
      "ComplianceType": "string",
      "ComplianceTypeID": "string",
      "ConsentGiven": "boolean",
      "PluginPreferences": "string",
      "ComplianceLawType": "string"
    }
  ],
  "IabConsents": [
    {
      "Name": "string",
      "Id": "integer",
      "ConsentGiven": "boolean",
      "ConsentType": "string"
    }
  ]
}

POST /api/consent

PUT /api/consent

Create a new consent or update an existing one if the client ID matches an existing record.

Request:

{
  "Domain": "string",
  "ClientId": "string",
  "AllConsents": [
    {
      "ComplianceType": "string",
      "LastUpdated": "string",
      "ComplianceTypeID": "string",
      "ConsentGiven": "boolean",
      "PluginPreferences": "string"
    }
  ],
  "PageURL": "string"
}

Response: 201 Created

PATCH /api/consent/customuserid/:clientId

[Authentication required]

Update the custom user ID associated with a consent.

Request:

{
  "DomainId": "string",
  "CustomUserId": "string"
}

Response: 200 OK

{
  "ClientId": "string",
  "CustomUserId": "string",
  "PageURL": "string",
  "Consents": [
    {
      "ComplianceType": "string",
      "ComplianceTypeID": "string",
      "ConsentGiven": "boolean",
      "PluginPreferences": "string",
      "ComplianceLawType": "string"
    }
  ],
  "IabConsents": [
    {
      "Name": "string",
      "Id": "integer",
      "ConsentGiven": "boolean",
      "ConsentType": "string"
    }
  ]
}