Purposes

A purpose is a specific, named reason for which you collect or process user data. When you display a consent prompt, each purpose tells the user exactly what they are agreeing to — for example, “Marketing Emails”, “Analytics”, or “Order Fulfillment”. Users can accept or decline each purpose individually (unless it is mandatory), and truConsent records those granular decisions in the consent log.

You configure purposes in the truConsent dashboard and attach them to collection points. The API surfaces purpose details when you fetch a banner so you can render consent choices to your users.

Note

Purposes are created and managed in the truConsent dashboard — you cannot create or update them through the API.

Purpose fields

Field	Type	Description
id	string (UUID)	Unique identifier for the purpose
display_id	string	Human-readable slug
name	string	Display name shown to users in the consent prompt
description	string	Explanation of why this data is collected and how it will be used
is_mandatory	boolean	If true, the user cannot decline this purpose
collection_style	string	How consent for this purpose is collected
expiry_period	string	How long the consent for this purpose remains valid
status	string	Whether the purpose is active or inactive

Mandatory vs. optional purposes

When is_mandatory is true, the purpose is required for your service to function and cannot be declined. Clearly distinguish mandatory purposes in your UI so users understand which processing activities are non-negotiable.

Optional purposes (is_mandatory: false) can be accepted or declined independently. A user who declines all optional purposes but accepts all mandatory ones produces an overall action of partial_consent in the consent log.

Tip

Reserve mandatory purposes for processing that is strictly necessary for service delivery — for example, fulfilling an order. Marking too many purposes as mandatory can erode user trust and may conflict with consent regulations in your jurisdiction.

Expiry period

The expiry_period field indicates how long a consent decision for this purpose remains valid. After the expiry period elapses, you should re-prompt the user for consent. The value is a human-readable label resolved from your configured expiry types (for example, "1 Year" or "6 Months").

Purpose relationships

Each purpose can be linked to other data governance objects in truConsent. These relationships appear in banner API responses so you can surface transparency information to users:

Relationship	Description
data_elements	The specific data fields processed under this purpose (for example, email address, purchase history)
processing_activities	The operations performed on the data (for example, sending emails, generating reports)
legal_entities	The legal entities or data processors involved in processing
tools	Third-party tools or vendors used to process the data

Consent suppression

If a user repeatedly declines an optional purpose that is configured as recurring, truConsent can stop showing that purpose to the user after a configurable threshold. Two settings in your banner global settings control this:

• suppression_threshold — the number of consecutive declines before suppression activates
• suppression_duration_days — how many days the purpose is suppressed after the threshold is reached

Suppression only applies to optional (is_mandatory: false) recurring purposes. Mandatory purposes are always shown.

Example: a purpose object

The following is a representative purpose object as returned by GET /banners/{banner_id}:

{
  "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "display_id": "marketing-emails",
  "name": "Marketing Emails",
  "description": "We use your email address to send you promotional offers, product updates, and newsletters. You can unsubscribe at any time.",
  "is_mandatory": false,
  "collection_style": "opt-in",
  "expiry_period": "1 Year",
  "status": "active",
  "consented": "declined",
  "data_elements": [
    {
      "id": "d1e2f3a4-b5c6-7890-defa-123456789012",
      "name": "Email Address",
      "display_id": "email-address"
    }
  ],
  "processing_activities": [
    {
      "id": "e2f3a4b5-c6d7-8901-efab-234567890123",
      "name": "Email Campaign Delivery",
      "display_id": "email-campaign-delivery"
    }
  ],
  "legal_entities": [
    {
      "id": "f3a4b5c6-d7e8-9012-fabc-345678901234",
      "name": "Acme Marketing Ltd.",
      "display_id": "acme-marketing"
    }
  ],
  "tools": [
    {
      "id": "a4b5c6d7-e8f9-0123-abcd-456789012345",
      "name": "SendGrid",
      "display_id": "sendgrid"
    }
  ]
}

The consented field reflects the user’s current consent status for this purpose. When fetching a banner without a specific user context, it defaults to "declined". When fetching a user-specific banner via GET /banners/user/{user_id}, this field is overlaid with the user’s most recent consent decision.