> For the complete documentation index, see [llms.txt](https://docs.mediarithmics.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/understand-mediarithmics-standard-objects/user-choice.md).

# UserChoice

The record of a user's choice for one of your processing activities, its fields, and how to declare it in the schema.

## Your goal

Know what a UserChoice holds and declare it in your schema, so that the platform can apply your users' choices and you can query them.

## Expected outcome

`UserChoice` is declared in your published schema with the properties you query on indexed, and you know where each of its fields comes from.

## What a UserChoice is

A **UserChoice** is the choice a user has made regarding data privacy and the data processing declared by your organisation. The platform uses it to adapt application behaviour to the user's choices automatically. Each UserChoice concerns one of your [processing activities](https://docs.mediarithmics.io/setup-and-monitor/ensure-privacy-and-compliance/manage-consent-and-processing-activities.md#processing-activities).

How choices are captured, and how they are enforced, is in [Manage consent & Processing activities](https://docs.mediarithmics.io/setup-and-monitor/ensure-privacy-and-compliance/manage-consent-and-processing-activities.md#user-choices).

## The UserChoice object

```json
{
    "$processing_id": "1004",
    "$choice_ts": 1561622248000,
    "$choice_acceptance_value": true,
    "$creation_ts": 1561622248000,
    "$channel_id": "1234",
    "$choice_source_id": "1001",
    "$user_agent_id": "vec:123456789",
    "$compartment_id": "1234",
    "$user_account_id": "123456789",
    "$email_hash": {
        "$hash": "a1b2c3d4e5",
        "$email": "random@example.com"
    },
    "custom_property_1": "custom_value_1"
}
```

| Field                                                                      | Description                                                                                                                                                                                                                                                                                                   |
| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `$processing_id`                                                           | The processing activity concerned. Mandatory by API; set automatically from `$processing_token` on a `$set_user_choice` event.                                                                                                                                                                                |
| `$choice_ts`                                                               | When the choice was given by the user. Mandatory by API; set automatically from the event's `$ts`.                                                                                                                                                                                                            |
| `$choice_acceptance_value`                                                 | The acceptance value. Mandatory by API; set automatically from the event property of the same name.                                                                                                                                                                                                           |
| `$creation_ts`                                                             | **System field.** The creation timestamp of the choice. Cannot be modified, by API or by event.                                                                                                                                                                                                               |
| `$channel_id`                                                              | The channel the choice was collected on. Optional by API; set automatically from the [activity origin](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time.md#activity-origin).                                                                            |
| `$choice_source_id`                                                        | The source of the choice. Optional by API; set automatically from `$choice_source_token`. See [When several sources set the same choice](https://docs.mediarithmics.io/setup-and-monitor/ensure-privacy-and-compliance/manage-consent-and-processing-activities.md#when-several-sources-set-the-same-choice). |
| `$user_agent_id`, `$user_account_id` with `$compartment_id`, `$email_hash` | The identifiers. From a `$set_user_choice` event they are copied from the activity; through the `/user_choices` API they come from the request payload, or from the URL if the payload has none.                                                                                                              |
| *any custom property*                                                      | Optional. Set automatically from the event's custom properties - this is where the evidence of a valid consent lives.                                                                                                                                                                                         |

## Declare choices in the schema

{% hint style="danger" %}
**User choices and their custom properties must be declared in the** [**schema**](https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md) **for the feature to work.**
{% endhint %}

Any property can be indexed, and these **should** be: `processing_id`, `choice_ts`, `creation_ts`, and `choice_acceptance_value`. The others - standard or custom - are mostly used to prove the validity of a choice, so indexing them may not be necessary.

```graphql
type UserPoint @TreeIndexRoot(index:"USER_INDEX") {
    id: ID!
    activity_events: [ActivityEvent!]!
    choices: [UserChoice!]!
}

type UserChoice {
    id: ID!
    processing_id: String! @TreeIndex(index:"USER_INDEX")
    choice_acceptance_value: Boolean! @TreeIndex(index:"USER_INDEX")
    choice_ts: Timestamp! @TreeIndex(index:"USER_INDEX")
    creation_ts: Timestamp! @TreeIndex(index:"USER_INDEX")
    channel_id: String
    user_agent_id: String
    email_hash: String
    compartment_id: String
    user_account_id: String
    custom_field: String @Property(path: "custom_field")
}
```

## Related pages

<table data-view="cards" data-search="false"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Manage consent &#x26; Processing activities</strong></td><td>Register processing activities, capture choices, and enforce them.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/ensure-privacy-and-compliance/manage-consent-and-processing-activities.md">Manage consent &amp; Processing activities</a></td></tr><tr><td><strong>Import user choices</strong></td><td>Loading the choices you already hold.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-user-choices.md">Import user choices</a></td></tr><tr><td><strong>Schema definition</strong></td><td>The default objects, and how to publish a schema.</td><td><a href="https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/schema-definition.md">Schema definition</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.mediarithmics.io/setup-and-monitor/collect-and-manage-your-data/design-your-data-model-and-schema/understand-mediarithmics-standard-objects/user-choice.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
