Consent API (v3)

The Consent v3 API requires Fides Cloud or Fides Enterprise. For more information, talk to our solutions team.

The Consent v3 API is the new interface for managing privacy preferences in Fides. It provides a unified set of endpoints for writing, reading, and reporting on consent data, with support for flexible identity types, notice hierarchies, and fine-grained filtering.

For conceptual background on how Fides handles consent, see Consent records.

⚠️ The v3 API is actively being developed and does not yet support all the features of the Consent v1 API.

Endpoints overview

All v3 endpoints require OAuth authentication. Include a valid access token in the Authorization header: Authorization: Bearer <access_token>. See Generating OAuth tokens for how to obtain one.

Writing preferences

Save preferences

POST /api/v3/privacy-preferences

Saves one or more consent preferences for an identity and returns the resulting current preferences.

Query parameters

Request body

Example

curl -X POST 'http://localhost:8080/api/v3/privacy-preferences?policy=cascade_down_opt_out' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identity": {
      "email": { "value": "user@example.com" }
    },
    "preferences": [\
      {\
        "notice_key": "marketing_advertising",\
        "notice_history_id": "pri_notice-history-abc-123",\
        "value": "opt_out"\
      },\
      {\
        "notice_key": "analytics",\
        "notice_history_id": "pri_notice-history-def-456",\
        "value": "opt_in"\
      }\
    ],
    "meta": {
      "method": "banner",
      "url": "https://example.com/products"
    }
  }'

Response

Returns the current preferences document for the identity after the save. If async=true, returns 202 Accepted with no body.

Reading preferences

Get current preferences

GET /api/v3/privacy-preferences/current

Retrieves the effective current preferences for a specific identity. Includes saved preferences and default values for any active notices where no explicit choice exists.

Query parameters

Example

curl -X GET 'http://localhost:8080/api/v3/privacy-preferences/current?identity.email=user@example.com' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Response

Returns the current preferences document with one entry per active notice. Each preference includes metadata indicating whether it was explicitly set, generated by a propagation policy, or assigned as a default.

List preference records

GET /api/v3/privacy-preferences

Retrieves stored preference records over time with cursor-based pagination. Supports filtering by identity, time window, and record type.

Query parameters

Example

curl -X GET 'http://localhost:8080/api/v3/privacy-preferences?identity.email=user@example.com&include_historical=true&size=50' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Response

{
  "items": [\
    {\
      "identity": {\
        "email": { "value": "user@example.com" }\
      },\
      "preferences": [\
        {\
          "notice_key": "marketing_advertising",\
          "value": "opt_out",\
          "collected_at": "2025-12-01T10:30:00Z"\
        }\
      ],\
      "is_latest": true\
    }\
  ],
  "next_cursor": "eyJpZCI6ICIxMjM0NTY3ODkwIn0=",  
  "total_count": 42
}

total_count is only included on the first page (when no cursor is supplied). Subsequent pages omit it to avoid the performance overhead.

Reporting

Count records

POST /api/v3/privacy-preferences/filter-stats

Returns an exact count of preference records matching the specified filters without returning the records themselves.

Request body

Example

curl -X POST 'http://localhost:8080/api/v3/privacy-preferences/filter-stats' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "start_time": "2025-01-01T00:00:00Z",
    "end_time": "2025-12-31T23:59:59Z",
    "include_latest": true,
    "include_historical": false
  }'

Preference metadata

Privacy preferences support metadata at two levels: a top-level meta object that describes the overall submission, and an optional per-preference meta on each individual preference item. Both levels accept arbitrary custom fields alongside a reserved fides namespace for standardized properties.

Top-level metadata

The top-level meta object captures context about how and where the preferences were collected. The fides namespace provides standardized fields for common consent metadata:

You can also include any custom key-value pairs alongside the fides namespace. Values can be strings, numbers, or nested objects:

{
  "meta": {
    "fides": {
      "geography": "US-CA",
      "method": "button",
      "property_id": "prop_123"
    },
    "campaign_id": "summer-2026",
    "source": {
      "platform": "mobile_app",
      "app_version": "3.2.1"
    }
  }
}

There are no restrictions on the keys or structure of custom metadata -- use whatever fields make sense for your reporting and auditing needs.

Per-preference metadata

Each preference item can also carry its own meta object. The fides namespace at this level supports:

Custom fields are accepted here as well.

Identity definitions

Identity definitions register the identity types your organization uses for storing and querying preferences. For conceptual background, see Identities.

List identity definitions

GET /api/v3/definitions/identities

Returns all registered identity definitions.

curl -X GET 'http://localhost:8080/api/v3/definitions/identities' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Accept: application/json'

Register an identity definition

POST /api/v3/definitions/identities

Registers a new identity type for use with privacy preferences.

curl -X POST 'http://localhost:8080/api/v3/definitions/identities' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "identity_key": "loyalty_id",
    "name": "Loyalty ID",
    "type": "string"
  }'

Remove an identity definition

DELETE /api/v3/definitions/identities/{identity_key}

Unregisters an identity type.

curl -X DELETE 'http://localhost:8080/api/v3/definitions/identities/loyalty_id' \
  -H 'Authorization: Bearer <access_token>'

[Consent API](/content/docs/consent/reference/consent-api "Consent API"/index.html) [Propagation Policies](/content/docs/consent/reference/propagation-policies "Propagation Policies"/index.html)