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.

Endpoint	Method	Purpose
`/api/v3/definitions/identities`	`GET`	List registered identity types
`/api/v3/definitions/identities`	`POST`	Register an identity type
`/api/v3/definitions/identities/{identity_key}`	`DELETE`	Remove an identity type
`/api/v3/privacy-preferences`	`GET`	List preference records over time
`/api/v3/privacy-preferences`	`POST`	Save preferences for an identity
`/api/v3/privacy-preferences/current`	`GET`	Get current preferences for an identity
`/api/v3/privacy-preferences/filter-stats`	`POST`	Count records matching a filter

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

Parameter	Type	Description
`async`	`boolean`	When `true`, returns `202 Accepted` and processes asynchronously. Default: `false`.
`policy`	`string`	Propagation policy to apply across notice hierarchies. Default: `cascade_down_opt_out`.
`response_notice_keys[]`	`string[]`	Filter which notice keys appear in the response. Does not affect what is saved.

Request body

Field	Type	Required	Description
`identity`	`object`	Yes	A map of identity keys to objects containing a `value` field. Built-in types like `email` and `phone_number` work out of the box; custom types must be registered as identity definitions first.
`preferences`	`array`	Yes	List of preference objects.
`preferences[].notice_key`	`string`	Yes	Stable key identifying the privacy notice.
`preferences[].notice_history_id`	`string`	Yes	Version of the notice the user was shown.
`preferences[].value`	`string`	Yes	One of: `opt_in`, `opt_out`, `acknowledge`.
`preferences[].collected_at`	`string`	No	ISO-8601 timestamp. Defaults to current server time if omitted.
`preferences[].meta`	`object`	No	Per-preference metadata. See Preference metadata.
`meta`	`object`	No	Top-level metadata about how and where consent was collected. See Preference metadata.

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

Parameter	Type	Description
`identity.<key>`	`string`	Required. At least one identity filter. Format: `identity.email=user@example.com`.
`notice_keys[]`	`string[]`	Only return preferences for the specified notice keys.
`include_descendants`	`boolean`	When `notice_keys` is provided, also include descendant notices. Default: `false`.

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

Parameter	Type	Description
`identity.<key>`	`string`	Filter by identity. Format: `identity.email=user@example.com`. Any registered identity type is supported.
`cursor`	`string`	Pagination cursor from a previous response's `next_cursor` field.
`size`	`integer`	Records per page. Default: `100`.
`start_time`	`string`	ISO-8601 timestamp. Records collected at or after this time.
`end_time`	`string`	ISO-8601 timestamp. Records collected at or before this time.
`time_inclusivity`	`string`	Boundary behavior for time filters: `both`, `start`, `end`, or `neither`. Default: `both`.
`include_latest`	`boolean`	Include the most recent record per identity. Default: `true`.
`include_historical`	`boolean`	Include older (non-latest) records. Default: `true`.

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

Field	Type	Description
`start_time`	`string`	ISO-8601 timestamp.
`end_time`	`string`	ISO-8601 timestamp.
`time_inclusivity`	`string`	One of: `both`, `start`, `end`, `neither`.
`include_latest`	`boolean`	Include latest records in the count.
`include_historical`	`boolean`	Include historical records in the count.

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:

Field	Type	Read-only	Description
`fides.geography`	`string`	No	The user's geography
`fides.method`	`string`	No	How consent was collected (e.g., `button`, `dismiss`, `gpc`, `save`)
`fides.request_origin`	`string`	No	The request origin from headers
`fides.truncated_ip_address`	`string`	No	Truncated IP address for reporting
`fides.recorded_url`	`string`	No	The referring URL from request headers
`fides.user_agent`	`string`	No	The user agent string
`fides.property_id`	`string`	No	The Fides property ID
`fides.created_at`	`string`	Yes	ISO-8601 timestamp of when the preference record was created in Fides

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:

Field	Type	Read-only	Description
`fides.property_id`	`string`	No	The Fides property ID where the preference was collected
`fides.experience_config_history_id`	`string`	No	Identifier for the experience config history
`fides.preference_type`	`string`	Yes	How the preference was created: `explicit` (user-submitted), `policy` (propagation policy-generated), or `default` (system-generated default)
`fides.policy_key`	`string`	Yes	The propagation policy that created this preference (only present when `preference_type` is `policy`)
`fides.source_preference`	`object`	Yes	The explicit preference that triggered propagation (only present when `preference_type` is `policy`). Contains `notice_key` and `notice_history_id` of the source.

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.

Field	Required	Description
`identity_key`	Yes	A unique key for the identity type (e.g., `loyalty_id`)
`name`	Yes	A human-readable display name
`type`	Yes	The data type: `string`, `uuid`, `integer`, `email`, or `phone_number`
`description`	No	An optional description

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>'

Cross-Device Identity Consent Records