> 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/import-data-in-batch/import-user-choices.md).

# Import user choices

Upsert or delete user choices in bulk with a USER\_CHOICE document import.

## Your goal

Load consent decisions into the datamart from a file, so the platform can apply them.

## Expected outcome

`UserChoice` records created or updated for the users in your file, against the processing activities you reference.

{% hint style="info" %}
This page is the **command reference** for the `USER_CHOICE` document import. For the wider job - where consent comes from, which route to use, and what has to exist first - see [Import user consent](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-user-consent.md).
{% endhint %}

## How to

{% stepper %}
{% step %}

### Create the document import

Document type `USER_CHOICE`, mime type `APPLICATION_X_NDJSON`. Only `ndjson` is supported for user choices.

```bash
curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/<DATAMART_ID>/document_imports \
  -H 'Authorization: <YOUR_API_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "document_type": "USER_CHOICE",
    "mime_type": "APPLICATION_X_NDJSON",
    "encoding": "utf-8",
    "name": "<YOUR_DOCUMENT_IMPORT_NAME>"
}'
```

{% endstep %}

{% step %}

### Create an execution with your choice commands

```bash
curl -X POST \
  https://api.mediarithmics.com/v1/datamarts/<DATAMART_ID>/document_imports/<DOCUMENT_IMPORT_ID>/executions \
  -H 'Authorization: <API_TOKEN>' \
  -H 'Content-Type: application/x-ndjson' \
  -d '{
        "operation": "UPSERT",
        "compartment_id": "<COMPARTMENT_ID>",
        "user_account_id": "<USER_ACCOUNT_ID>",
        "force_replace": true,
        "user_choice": {
              "$processing_id": "<PROCESSING_ID>",
              "$choice_ts": "<CHOICE_TS>"
        }
      }'
```

{% endstep %}

{% step %}

### Read the result

Check `total_success`, `total_failure`, and the error file. See [reading the result](/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch.md#reading-the-result).
{% endstep %}
{% endstepper %}

{% hint style="success" %}
You can upload many choices at once. The data is `ndjson`, so choices are separated by `\n`, not by commas.
{% endhint %}

## The user choice command

| Field             | Type             | Description                                                                                                                                                                   |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `operation`       | Enum             | `UPSERT` or `DELETE`.                                                                                                                                                         |
| `compartment_id`  | String, optional | The compartment ID, as an identifier together with `user_account_id`.                                                                                                         |
| `user_account_id` | String, optional | The account ID, as an identifier together with `compartment_id`.                                                                                                              |
| `email_hash`      | String, optional | The email hash, as an identifier.                                                                                                                                             |
| `user_agent_id`   | String, optional | The device technical identifier, as an identifier.                                                                                                                            |
| `force_replace`   | Boolean          | **Mandatory when the operation is `UPSERT`.** `true` replaces the user choice entirely with the object in `user_choice`. `false` merges that object into the existing choice. |
| `user_choice`     | JSON object      | **Mandatory when the operation is `UPSERT`.** The user choice object.                                                                                                         |

Inside `user_choice`:

* `$processing_id` is **always mandatory**.
* `$choice_ts` is **mandatory when the operation is `UPSERT`**.

{% hint style="warning" %}
**Only one identifier is allowed per line.** Do not specify a user agent ID on a line that already carries an email hash.
{% endhint %}

## Verify

* The execution reports the expected success count.
* A user choice can be read back for a test user - see [Server-side events](/setup-and-monitor/collect-and-manage-your-data/collect-data-in-real-time/server-side-events.md#create-or-update-a-user-choice) for the read endpoints.
* The processing ID referenced exists as a processing activity.

## 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>Import user consent</strong></td><td>The wider job, and which route to choose.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-user-consent.md">Import user consent</a></td></tr><tr><td><strong>Manage consent &#x26; Processing activities</strong></td><td>What a processing activity and a user choice are.</td><td><a href="/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 data in batch</strong></td><td>Document imports, executions, and results.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch.md">Import data in batch</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/import-data-in-batch/import-user-choices.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.