Collect and record consent

truConsent separates the data layer from the UI layer: you own the consent banner interface, and truConsent stores the decisions. This guide walks you through fetching the banner configuration, rendering the UI, recording the user’s choices, and checking whether a user has already given consent so you can avoid prompting them unnecessarily.

Fetch the banner configuration

Before rendering a consent UI, fetch the banner’s configuration. The response contains your collection point details, the list of purposes, your organization’s branding, and the global banner settings.

curl https://api.truConsent.io/banners/{banner_id} \
  -H "X-API-Key: YOUR_API_KEY"

Replace {banner_id} with the display_id of the collection point you configured in your dashboard.

The response includes:

{
  "banner_id": "cp_signup_form",
  "collection_point": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Sign-up Consent",
  "version": "1",
  "consent_type": "opt-in",
  "purposes": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000001",
      "name": "Marketing communications",
      "is_mandatory": false,
      "expiry_period": "1 year",
      "consented": "declined"
    },
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000002",
      "name": "Analytics",
      "is_mandatory": false,
      "expiry_period": "6 months",
      "consented": "declined"
    }
  ],
  "organization": {
    "name": "Acme Corp",
    "logo_url": "https://cdn.example.com/logo.png"
  },
  "banner_settings": {
    "primary_color": "#689e1e",
    "action_button_text": "Accept all",
    "reject_all_text": "Reject all",
    "banner_title": "Your privacy choices",
    "footer_text": "You can change your preferences at any time."
  }
}

Use purposes to render each choice in your UI. The banner_settings fields control copy and styling so your consent UI stays in sync with what was configured in the dashboard.

Render the consent UI

Build the consent banner using the data from the previous step. You are responsible for the UI — truConsent only provides and stores the data.

A few things to keep in mind:
- Purposes where is_mandatory: true should be pre-selected and non-editable.
- Display the name field for each purpose as the toggle label.
- Use banner_settings.banner_title and banner_settings.footer_text for your header and footer copy.
- Show organization.logo_url if you want branded banners.
Once the user makes their selections, proceed to the next step to record them.

Record the user’s consent decision

Post the user’s decision to truConsent as soon as they interact with the banner. Use the collection_point_id value returned in the banner response.

curl -X POST https://api.truConsent.io/consent/{collection_point_id}/consent \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "user_123",
    "action": "partial_consent",
    "purposes": [
      {
        "id": "a1b2c3d4-0000-0000-0000-000000000001",
        "name": "Marketing communications",
        "consented": "approved",
        "is_mandatory": false,
        "purpose_type": null
      },
      {
        "id": "a1b2c3d4-0000-0000-0000-000000000002",
        "name": "Analytics",
        "consented": "declined",
        "is_mandatory": false,
        "purpose_type": null
      }
    ],
    "requestId": null,
    "metadata": {}
  }'

action describes the user’s overall decision for the collection point:

Value	When to use
`approved`	User accepted all purposes
`declined`	User declined all purposes
`partial_consent`	User approved some purposes and declined others
`revoked`	User is withdrawing previously given consent
`no_action`	Banner was shown but the user dismissed without deciding

For each item in purposes, set consented to "approved" or "declined" to reflect the individual choice.

A successful response returns HTTP 201 with the created consent record:

{
  "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "action": "partial_consent",
  "collection_point_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "purpose_consents": [
    {
      "purpose_id": "a1b2c3d4-0000-0000-0000-000000000001",
      "purpose_name": "Marketing communications",
      "status": "approved",
      "is_mandatory": false,
      "purpose_type": null,
      "purpose_version": 1
    },
    {
      "purpose_id": "a1b2c3d4-0000-0000-0000-000000000002",
      "purpose_name": "Analytics",
      "status": "declined",
      "is_mandatory": false,
      "purpose_type": null,
      "purpose_version": 1
    }
  ],
  "timestamp": "2026-04-21T10:30:00.000000",
  "status": "pending",
  "request_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
}

Store the id or request_id if you need to reference this consent record later.

Check for existing consent before showing the banner

Prompting users who have already given consent creates a poor experience. Before rendering the banner, check whether this user has a previous consent record for the collection point.
Terminal window
```
curl "https://api.truConsent.io/consent/{collection_point_id}/previous-consent?userId=user_123" \
  -H "X-API-Key: YOUR_API_KEY"
```
If a previous decision exists, the response looks like this:
```
{
  "has_previous_consent": true,
  "previous_consent": {
    "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "action": "partial_consent",
    "purpose_consents": [
      {
        "purpose_id": "a1b2c3d4-0000-0000-0000-000000000001",
        "status": "approved"
      },
      {
        "purpose_id": "a1b2c3d4-0000-0000-0000-000000000002",
        "status": "declined"
      }
    ],
    "timestamp": "2026-04-21T10:30:00.000000"
  }
}
```
If has_previous_consent is true, skip the banner and apply the preferences from previous_consent.purpose_consents. If it is false, show the banner so the user can make their choices.

The previous consent check excludes records with action: "no_action", so a user who dismissed the banner without deciding is still treated as not having consented.