Consent model

Every time a user makes a consent decision in your app, truConsent records it as an immutable entry in the consent log. That log is the source of truth for your compliance audit trail. Understanding the model — what an action is, how purposes are tracked per decision, and how the log is structured — lets you query, display, and act on consent data with confidence.

Actions

An action describes the outcome of a consent decision. When you record or retrieve consent, the action field will be one of the following values:

approved

The user has given consent. All purposes (or the single purpose, if one was specified) were accepted.

{ "action": "approved" }

declined

The user has refused consent. No purposes were accepted.

{ "action": "declined" }

partial_consent

The user consented to some purposes but not all. Use the purpose_consents array to see which purposes were accepted and which were declined.

{ "action": "partial_consent" }

revoked

The user has withdrawn previously given consent.

{ "action": "revoked" }

no_action

The user dismissed the consent prompt without making a decision. This state does not appear in consent history queries.

{ "action": "no_action" }

Note

no_action is recorded at the time of dismissal but is excluded from history queries (GET /consent/{collection_point_id}/consents). Only decisive actions — approved, declined, partial_consent, and revoked — appear in the consent history.

The consent log

Every consent decision creates a new, timestamped entry in the consent log. The log is append-only — existing entries are never modified or deleted. This immutability is what makes the log a reliable compliance audit trail: you can always look back at exactly what a user decided, and when.

When you fetch a user’s consent history, entries are returned in reverse chronological order so the most recent decision appears first.

Purpose consents

A single consent action can cover multiple purposes. The purpose_consents field is an array that breaks down the consent decision per purpose. This is how truConsent tracks granular opt-ins — for example, a user might approve “Order Fulfillment” while declining “Marketing Emails” in a single interaction, resulting in an overall partial_consent action.

Each entry in purpose_consents includes:

Field	Description
purpose_id	UUID of the purpose
purpose_name	Display name of the purpose
status	approved or declined for this specific purpose
is_mandatory	Whether the purpose could not be declined
purpose_version	Version of the purpose definition at the time of consent
purpose_type	The purpose category type

{
  "purpose_consents": [
    {
      "purpose_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "purpose_name": "Order Fulfillment",
      "status": "approved",
      "is_mandatory": true,
      "purpose_version": 1,
      "purpose_type": "operational"
    },
    {
      "purpose_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "purpose_name": "Marketing Emails",
      "status": "declined",
      "is_mandatory": false,
      "purpose_version": 2,
      "purpose_type": "marketing"
    }
  ]
}

Consent record fields

A full consent log entry contains the following fields:

Field	Type	Description
id	string (UUID)	Unique identifier for this consent record
action	string	The overall consent decision (see Actions)
purpose_consents	array	Per-purpose consent breakdown
timestamp	string (ISO 8601)	When the decision was recorded
request_id	string	Your external request identifier, or a system-generated UUID
status	string	Processing status of the record (for example, pending)
metadata	object	Arbitrary key-value data you passed when recording consent

Example of a complete consent log entry:

{
  "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "action": "partial_consent",
  "purpose_consents": [
    {
      "purpose_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "purpose_name": "Order Fulfillment",
      "status": "approved",
      "is_mandatory": true,
      "purpose_version": 1,
      "purpose_type": "operational"
    },
    {
      "purpose_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "purpose_name": "Marketing Emails",
      "status": "declined",
      "is_mandatory": false,
      "purpose_version": 2,
      "purpose_type": "marketing"
    }
  ],
  "timestamp": "2024-03-15T10:32:00.000Z",
  "request_id": "req_9f8e7d6c5b4a3210",
  "status": "pending",
  "metadata": {
    "session_id": "sess_abc123",
    "ip_country": "IN"
  }
}