> 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-segments.md).

# Import segments

Add users to a segment, or remove them, from a file of identifiers.

## Your goal

Place a list of users into one or more segments - an email list, a cookie list, a list of account IDs - or take them out again.

## Expected outcome

The users in your file appear in the target segments, with the expiration behaviour you specified.

## How to

{% stepper %}
{% step %}

### Create the document import

Document type `USER_SEGMENT`, mime type `APPLICATION_X_NDJSON` **or** `TEXT_CSV`.

{% hint style="info" %}
`USER_SEGMENT` is the only document type that accepts `TEXT_CSV`. Every other import is `ndjson` only.
{% endhint %}

```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_SEGMENT",
    "mime_type": "APPLICATION_X_NDJSON",
    "encoding": "utf-8",
    "name": "<YOUR_DOCUMENT_IMPORT_NAME>"
}'
```

{% endstep %}

{% step %}

### Create an execution with your segment 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": "UPDATE",
        "expiration_duration": 0,
        "compartment_id": "<COMPARTMENT_ID>",
        "user_account_id": "<USER_ACCOUNT_ID>",
        "segment_id": "<SEGMENT_ID>"
      }'
```

{% 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" %}
`UPDATE` and `DELETE` operations can be mixed in the same file upload.

With `ndjson`, lines are separated by `\n`, not by commas.
{% endhint %}

## The segment command

| Field                     | Type                          | Description                                                                                            |
| ------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------ |
| `operation`               | Enum, **mandatory**           | `UPDATE` or `DELETE`.                                                                                  |
| `expiration_duration`     | Integer, **mandatory**        | The number of minutes before the user is removed from the segment. `0` means the user never leaves it. |
| `compartment_id`          | String, optional              | The compartment ID, as an identifier together with the account ID.                                     |
| `user_account_id`         | String, optional              | The account ID, as an identifier together with the compartment ID.                                     |
| `email_hash`              | String, optional              | The email hash, as an identifier.                                                                      |
| `user_agent_id`           | String, optional              | The user agent ID, as an identifier.                                                                   |
| `segment_id`              | String, optional              | The ID of the segment the user is inserted into or deleted from.                                       |
| `segment_ids`             | List of strings, optional     | Several segment IDs, for example `["segment_id_1","segment_id_2"]`.                                    |
| `segment_technical_name`  | String, optional              | The technical name of the segment.                                                                     |
| `segment_technical_names` | List of strings, optional     | Several technical names, for example `["technical_name_1","technical_name_2"]`.                        |
| `expiration_ts`           | Number, optional              | The timestamp at which the user expires from the segment. `0` means the user never leaves it.          |
| `data_bag`                | Escaped JSON string, optional | The data bag associated with the user–segment relationship.                                            |

{% hint style="success" %}
Use `segment_ids` or `segment_technical_names` when a single user has to be handled in several segments - it avoids one line per segment per user.
{% endhint %}

{% hint style="warning" %}
**Only one identifier is allowed per line.** Different lines in the same file may use different identifier types.
{% endhint %}

## Choosing between duration and timestamp

`expiration_duration` is relative to the import, `expiration_ts` is absolute. Pick according to what your list means:

| You want                                                                          | Use                   |
| --------------------------------------------------------------------------------- | --------------------- |
| Membership for a fixed window after the import, such as a 30-day retargeting list | `expiration_duration` |
| Membership until a specific date, such as the end of a campaign                   | `expiration_ts`       |
| Permanent membership until you remove it                                          | either, set to `0`    |

## Verify

* The execution reports the success count you expected.
* The segment's user count moves by roughly the number of lines imported - allowing for users already in it.
* A user from the file appears in the segment, and leaves it when the expiration is reached.

## 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>Load segments</strong></td><td>The same import through the Data loader interface.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/data-loader/load-segments.md">Load segments</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><tr><td><strong>Import profiles</strong></td><td>Importing the data behind the list.</td><td><a href="/setup-and-monitor/collect-and-manage-your-data/import-data-in-batch/import-profiles.md">Import profiles</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-segments.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.