User consent status

GET /api/v1/external/consents/user-status

Use this endpoint to get a complete picture of where a user stands on consent across your entire application. The response returns one entry per collection point the user has ever interacted with, each containing the most recent consent log entry for that collection point.

This is the recommended endpoint for enforcement checks — for example, before sending a marketing email, query this endpoint to confirm the user has an approved action for the relevant collection point.

Authentication

Both headers are required.

Header	Type	Required	Description
X-Org-Id	string	Yes	Your organization slug
X-API-Key	string	Yes	Your tenant API key

Query parameters

Parameter	Type	Required	Description
userId	string	Yes	The user ID whose full consent status you want to retrieve

Response

200 OK

Field	Type	Description
user_id	string	The user ID that was queried
total_consents	integer	Total number of consent log entries recorded for this user across all collection points
collection_points	array	One entry per collection point the user has interacted with
timestamp	string	ISO 8601 timestamp of when this response was generated, in UTC

collection_points[] fields:

Field	Type	Description
collection_point	object	Metadata about the collection point
latest_consent	object	The most recent consent log entry for this user at this collection point. null if no consent has been recorded.

collection_point fields:

Field	Type	Description
id	string	UUID of the collection point
display_id	string	Human-readable identifier
name	string	Display name
description	string	Description, or null
consent_type	string	The consent collection method, or null

latest_consent fields:

Field	Type	Description
id	string	UUID of the consent log entry
action	string	The recorded decision: approved, declined, partial_consent, revoked, or no_action
purpose_consents	array	Per-purpose breakdown
timestamp	string	ISO 8601 timestamp
status	string	Processing status
request_id	string	Request identifier

Errors

Status	Description
400	userId query parameter is missing, or X-Org-Id could not be resolved
401	X-API-Key is invalid or missing
403	API key lacks the admin scope
404	The user has no consent records in the system
500	Internal server error

Example

curl --request GET \
  --url 'https://truapi-dev.truconsent.io/api/v1/external/consents/user-status?userId=usr_7f3a9b21' \
  --header 'X-Org-Id: acme' \
  --header 'X-API-Key: tck_live_xxxxxxxxxxxx'

{
  "user_id": "usr_7f3a9b21",
  "total_consents": 3,
  "collection_points": [
    {
      "collection_point": {
        "id": "a0b1c2d3-1111-2222-3333-444455556666",
        "display_id": "cp_signup_form",
        "name": "Sign-up form",
        "description": "Consent collected at new user registration",
        "consent_type": "explicit"
      },
      "latest_consent": {
        "id": "c1d2e3f4-aaaa-bbbb-cccc-ddddeeeeeeee",
        "action": "partial_consent",
        "purpose_consents": [
          {
            "purpose_id": "3d6e2f1a-bc74-4e9a-a801-123456789abc",
            "purpose_name": "Marketing emails",
            "status": "approved",
            "is_mandatory": false,
            "purpose_type": "marketing",
            "purpose_version": 1
          }
        ],
        "timestamp": "2026-04-21T10:34:52.123456",
        "status": "pending",
        "request_id": "req_external_8821"
      }
    }
  ],
  "timestamp": "2026-04-21T11:00:00.000000Z"
}