Query a user's Record of Consent

Query the Record of Consent (ROC) timeline for a single user. Every consent update that Transcend archives for that user is returned as one record, oldest first, so you can reconstruct what the user consented to at any point in time.

Each record reports the cumulative purpose and preference state at that timepoint, plus a diff against the previous record. Pass includeRawRequest to also receive the original archived payload for each record.

Rate Limits

• 100 requests per organization per minute (default).
• This limit can be increased 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.

Timeline ordering and diffs

• Records are returned most recent first, in chronological order.
• preferencesAtCurrentTime is the full cumulative state of every purpose the user has ever set at the time that record was received.
• changeFromPrevState splits the change introduced by the record into added, removed and updated purposes. It is absent on the first record in the timeline, because there is no earlier record to compare against.
• Diffs are computed at the purpose and preference level only. IAB strings (tcf, gpp, usp) are not diffed — set includeRawRequest to true and compare consecutive raw payloads if you need to audit those.

Limits

• This endpoint is not cursor-paginated. Omit limit to receive the entire timeline in one response.
• limit must be between 1 and 200. When provided, the most recent limit records are returned.
• containsInitialRecord is always computed against the full timeline, even when limit truncates the returned records. It tells you whether the archive still holds the very first consent record for this user, which is what determines whether the timeline contains the true starting point or a partial view.

Identifiers

• Provide a single plaintext identifier. The gateway validates, normalizes and encrypts it before the lookup, so plaintext identifiers never reach Transcend storage.
• identifier.name defaults to the primary identifier configured for the partition, which is email unless you have configured otherwise.
• The lookup expands to every identifier linked to the same user, so querying by phone number returns the same timeline as querying by that user’s email.
• Identifiers inside rawRequest are decrypted by your Sombra before being returned on this endpoint.

Raw archived records

• rawRequest is present only when includeRawRequest is true.
• Unlike preferencesAtCurrentTime, a raw record reflects exactly what was submitted: consent may be null to indicate the purpose was cleared, and choice may be null to indicate a preference was cleared.

Empty results

• A user with no archived consent history returns { "records": [], "containsInitialRecord": false } rather than a 404.