Transcend Docs
API referencePreferences (Server-Side)

Query user preferences

POST
/v1/preferences/{partition}/query

Query preferences for multiple users

Rate Limits

  • 3000 requests per organization per minute (default).
  • This limit can be adjusted per organization upon request.

Rate Limiting Headers

  • X-RateLimit-Limit: The maximum number of requests allowed in the current window.
  • X-RateLimit-Remaining: The number of requests remaining in the current window.
  • X-RateLimit-Reset: The time at which the current rate limit window resets in ISO 8601 format.
  • Retry-After: (on 429) The number of seconds to wait before making a new request.

Querying by Transcend ID

  • Every preference record has a system-managed transcend identifier — a stable UUID automatically assigned by the system.
  • Use { "name": "transcend", "value": "<uuid>" } in filter.identifiers to query by Transcend ID.
  • Transcend ID is returned in all query responses alongside other identifiers.
  • Query multiple records by providing multiple transcend entries in the filter.identifiers array.

Per-purpose timestamps

  • Query responses include purposes[].timestamp as an ISO 8601 timestamp for each purpose value.

Source system

  • Query responses may include purposes[].sourceSystem when the purpose was last updated with an external system tag for audit purposes.

Authorization

Transcend_API_Key View Managed Consent Database Admin API
headerAuthorizationBearer <token>

authorization: Bearer <>

Scope: View Managed Consent Database Admin API

Path Parameters

partition*string

The ID of the partition in the Preference Store.

Header Parameters

authorization*string

An API key generated from the Transcend dashboard: https://app.transcend.io/infrastructure/api-keys.

x-sombra-authorization?string

The Sombra internal key. This header is only needed for self-hosted Sombra gateways. See https://docs.transcend.io/docs/dsr-automation/api-integration/authentication#authenticating-to-sombra

content-type*string

Specify content-type: application/json for a JSON response from the Transcend API.

Matchapplication-json

Request Body

application/json
  1. body
filter?||

The filter to apply to the query.

limit?number

Max number of users to return.

Range1 <= value <= 50
Default10
cursor?string

Opaque pagination cursor returned in the cursor field of a previous response. Pass it back to fetch the next page of results.

Response Body

Returns a list of users' preferences

application/json
  1. response
nodes*array<>

List of all user preference records that match the query filters.

Items1 <= items
cursor?string

The cursor for the next page. This is an opaque value that our servers use to track the next page of results.

curl -X POST 'https://multi-tenant.sombra.transcend.io/v1/preferences/string/query' \  -H 'authorization: string' \  -H 'content-type: string' \  -H 'Content-Type: application/json' \  -d '{  "filter": {    "identifiers": [      {        "name": "email",        "value": "no-track@example.com"      }    ]  }}'
Example Response
{  "nodes": [    {      "identifiers": [        {          "name": "transcend",          "value": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"        },        {          "name": "email",          "value": "no-track@example.com"        },        {          "name": "phone",          "value": "+11234567890"        }      ],      "partition": "ee1a0845-694e-4820-9d51-50c7d0a23467",      "timestamp": "2023-04-11T15:09:28.403Z",      "purposes": [        {          "purpose": "Advertising",          "enabled": true,          "timestamp": "2026-01-15T12:05:00.000Z"        },        {          "purpose": "Analytics",          "enabled": true,          "timestamp": "2026-01-15T12:05:00.000Z"        },        {          "purpose": "ProductUpdates",          "enabled": true,          "timestamp": "2026-01-15T12:05:00.000Z",          "preferences": [            {              "topic": "Frequency",              "choice": {                "selectValue": "Weekly"              }            },            {              "topic": "Channel",              "choice": {                "selectValues": [                  "Email",                  "Sms"                ]              }            },            {              "topic": "GoDigital",              "choice": {                "booleanValue": true              }            }          ]        }      ],      "consentManagement": {        "airgapVersion": null,        "usp": null,        "gpp": null,        "tcf": null      },      "system": {        "updatedAt": "2023-06-13T08:02:21.793Z",        "decryptionStatus": "DECRYPTED"      },      "metadata": [        {          "key": "version",          "value": "1.0.0"        },        {          "key": "confirmationTimestamp",          "value": "2023-06-13T07:03:12.621Z"        }      ],      "metadataTimestamp": "2023-06-13T08:02:21.793Z"    },    {      "identifiers": [        {          "name": "transcend",          "value": "b2c3d4e5-f6a7-8901-bcde-f12345678901"        },        {          "name": "email",          "value": "no-track-pls@example.com"        },        {          "name": "phone",          "value": "+11234567891"        }      ],      "partition": "ee1a0845-694e-4820-9d51-50c7d0a23467",      "timestamp": "2023-05-11T15:09:28.403Z",      "purposes": [        {          "purpose": "SaleOfInfo",          "enabled": false,          "timestamp": "2026-01-15T12:05:00.000Z"        }      ],      "consentManagement": {        "airgapVersion": null,        "gpp": null,        "tcf": null,        "usp": "1YYN"      },      "system": {        "updatedAt": "2023-06-13T08:02:21.793Z",        "decryptionStatus": "DECRYPTED"      },      "metadata": [        {          "key": "version",          "value": "1.0.0"        },        {          "key": "confirmationTimestamp",          "value": "2023-06-13T07:03:12.621Z"        }      ],      "metadataTimestamp": "2023-06-13T08:02:21.793Z"    }  ]}

Upsert user preferences PUT

Previous Page

Delete preference records POST

Next Page