# Consent API (v3)

The Consent v3 API requires Fides Cloud or Fides Enterprise. For more information, [talk to our solutions team.](/content/speak-with-us?utm_source=docs-site/index.html)

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](/content/docs/consent/concepts/fundamentals/identities/index.html), [notice hierarchies](/content/docs/consent/reference/propagation-policies/index.html), and fine-grained filtering.

For conceptual background on how Fides handles consent, see [Consent records](/content/docs/consent/concepts/fundamentals/consent-records/index.html).

⚠️ The v3 API is actively being developed and does not yet support all the features of the [Consent v1 API](/content/docs/consent/reference/consent-api/index.html).

## 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](/content/docs/api-reference/auth/generating-tokens/index.html) for how to obtain one.

| Endpoint | Method | Purpose |
| --- | --- | --- |
| `/api/v3/definitions/identities` | `GET` | [List registered identity types](/content/docs/consent/reference/consent-api-v3#list-identity-definitions/index.html) |
| `/api/v3/definitions/identities` | `POST` | [Register an identity type](/content/docs/consent/reference/consent-api-v3#register-an-identity-definition/index.html) |
| `/api/v3/definitions/identities/{identity_key}` | `DELETE` | [Remove an identity type](/content/docs/consent/reference/consent-api-v3#remove-an-identity-definition/index.html) |
| `/api/v3/privacy-preferences` | `GET` | [List preference records](/content/docs/consent/reference/consent-api-v3#list-preference-records/index.html) over time |
| `/api/v3/privacy-preferences` | `POST` | [Save preferences](/content/docs/consent/reference/consent-api-v3#save-preferences/index.html) for an identity |
| `/api/v3/privacy-preferences/current` | `GET` | [Get current preferences](/content/docs/consent/reference/consent-api-v3#get-current-preferences/index.html) for an identity |
| `/api/v3/privacy-preferences/filter-stats` | `POST` | [Count records](/content/docs/consent/reference/consent-api-v3#count-records/index.html) matching a filter |

## Writing preferences

### Save preferences

```plaintext
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](/content/docs/consent/reference/propagation-policies/index.html) 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](/content/docs/consent/reference/consent-api-v3#identity-definitions/index.html) 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](/content/docs/consent/reference/consent-api-v3#preference-metadata/index.html). |
| `meta` | `object` | No | Top-level metadata about how and where consent was collected. See [Preference metadata](/content/docs/consent/reference/consent-api-v3#preference-metadata/index.html). |

#### Example

```plaintext
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

```plaintext
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

```plaintext
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](/content/docs/consent/reference/consent-api-v3#preference-metadata/index.html) indicating whether it was explicitly set, generated by a [propagation policy](/content/docs/consent/reference/propagation-policies/index.html), or assigned as a default.

### List preference records

```plaintext
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](/content/docs/consent/concepts/fundamentals/identities/index.html) 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

```plaintext
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

```json
{
  "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

```plaintext
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

```plaintext
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](/content/docs/consent/guides/properties/index.html) 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:

```json
{
  "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](/content/docs/consent/guides/properties/index.html) ID where the preference was collected |
| `fides.experience_config_history_id` | `string` | No | Identifier for the [experience config](/content/docs/api-reference/manage/experience-config/index.html) history |
| `fides.preference_type` | `string` | Yes | How the preference was created: `explicit` (user-submitted), `policy` ( [propagation policy](/content/docs/consent/reference/propagation-policies/index.html)-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](/content/docs/consent/concepts/fundamentals/identities/index.html).

### List identity definitions

```plaintext
GET /api/v3/definitions/identities
```

Returns all registered identity definitions.

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

### Register an identity definition

```plaintext
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 |

```plaintext
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

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

Unregisters an identity type.

```plaintext
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)