> For the complete documentation index, see [llms.txt](https://help.smartico.ai/welcome/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.smartico.ai/welcome/products/crm-automation/segmentation/imported-segments.md).
# Imported Segments
### Overview
Imported segments are used for two purposes:
* You have a custom list of players that you build outside of Smartico and you want to make a segment from them
* You want to update some properties in Smartico side with data that is not available in the normal integration flow between your platform and Smartico.
### How to Import a Segment
To create an imported segment navigate to the Segments section, click the **Create** button, and select the **Import segment** option:
Once clicked It will open a window where you'll have to add a name for the segment and upload the already prepared CSV file. Please note that there is a special formatting required for the data in order for the import to be successful. You can also download a template of the CSV file.
Depending on a Label setting in the CSV file, you must have one or two mandatory columns - the *user\_ext\_id* and *core\_sm\_brand\_id.* In most cases the only mandatory column is user\_ext\_id.
***user\_ext\_id** -* is the user's external ID (without the brand indication in the beginning):
***core\_sm\_brand\_id -***** is** the brand ID for the brand of which the given user belongs. You can find this number in the user profile, the number standing before the user's external ID. In the example case is 31.
When the label setting requires the ***core\_sm\_brand\_id*** column, Smartico uses it to find the right player when the same user\_ext\_id exists in more than one brand. For example, you have a user with ID 55 in brand A and a user with the same ID in brand B. When the setting does not require this column, Smartico matches players by user\_ext\_id only, even if the file has a core\_sm\_brand\_id column. In this case, if the same user\_ext\_id exists in more than one brand, all these players are added to the segment. To change this setting, contact your Success Manager.
### Affiliate Operator Identifier
If your label operates in Affiliate Operator mode, the mandatory column is **affiliate\_id** instead of **user\_ext\_id**. The template downloaded from the Back-Office automatically provides the required columns for affiliate imports.
Once prepared the CSV file should look like this:
After adding the file, a quick check will identify any errors in the uploaded user data. Once the check is completed, you can proceed with the import by clicking **Continue**.
Once you click "Continue", the file validation process will begin. During this phase, you can decide whether to proceed with the import or stop the process.
If you choose to proceed with importing the CSV file, the import process will begin, and the segment will be created. However, it will remain in the 'Importing' status until all users are successfully imported.
You can check the Import status inside the segment as well.
After the import is complete, you can view the successfully imported users under the **Users in CSV** tab. Any users who do not match existing user external IDs in the system are also shown under the **Users in CSV** tab with the status **No matching users**.
### Updating other properties of user while importing segment
You can add multiple columns in your CSV with names that correspond to name of properties in Smartico system. For example you have found that some deposits were not sent to Smartico and you want to update properties **acc\_last\_deposit\_date** and **acc\_last\_deposit\_amount**. You will need to prepare a file with additional columns exactly with these names and values for users that you want to update. For the format of values, please see table below.
### CSV Import – Guidelines & Rules
When creating a **CSV Segment**, please follow these important rules and behaviors to ensure a successful upload:
#### ✅ **File Requirements**
* The file must be in **plain text CSV** format (comma-separated).
* **Do not use unnecessary quotation marks** in simple text or numeric fields. Quotation marks are only required when escaping array properties (such as user markers/tags) or fields containing commas.
* Each property in the file must match a supported **data type** (see below).
#### **📊 Supported Data Types**
| Data Type | Description |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `string` | Text values |
| `numeric` | Numbers only |
| `enum` | Numeric enumeration values |
| `boolean` | Use `true/false` or `1/0` |
| `date` |
Different date formats are supported such as:
YYYY-MM-DD → 2024-03-25
YYYY-MM-DD hⓂ️s → 2024-03-25 22:22:32
MM-DD-YYYY → 03-25-2024
MM-DD-YYYY hⓂ️s → 03-25-2024 22:22:53
\*below you can find the full list with supported date formats
2. Timestamp in milliseconds (e.g. 1704147742000). Use an Epoch converter to convert dates
2. **Full Import:**
* If invalid values are found **after** the first 20 users, those specific rows will be **skipped** and there is a message with the number of the skipped users.
### Validation Confirmation Timeout
Once the full validation completes, the Back-Office shows how many records are valid and asks **Do you want to proceed with segment import?** The segment is created only when you click **Import**. If you click **Cancel** or close the window, no segment is created, and you can upload the file again.
#### 🚫 Unsupported Properties
* Some user properties **cannot be updated via CSV import**. If the file has a column for such a property, or a column that is not a property name, the check shows the error "Properties names: ... are not defined in the system" and you cannot continue. Remove these columns from the file.
* System columns from a segment export (`smartico_user_id`, `user_id`, `crm_brand_id`, `crm_brand_name`, `ext_brand_id`) appear **greyed out** in the UI and are **skipped automatically** during the upload.
### Update points/gems/diamonds via CSV
You can update points, gems, and diamonds for specific users via CSV.\
Using the **‘Import Segment’** feature in Segments, you can upload a CSV file and choose to add, deduct, or set values for user balances.
The required columns in the CSV depend on what you want to update and the type of operation. Below are the supported columns:
* `ach_points_balance` – updates current points (used for store, tournaments, mini-games)
* `ach_points_ever` – updates level progress points (only for leveling)
* `ach_points_leaderboard` – updates leaderboard ranking points
* `ach_gems_balance` – updates current gems balance
* `ach_diamonds_balance` – updates current diamonds balance
* `operation_type` – required when updating any balance;
* options: **add, deduct, set**
{% hint style="warning" %}
Note: If you're updating any currency column, the `operation_type` column is mandatory.
{% endhint %}
BO: Update points/gems/diamonds via Import Segment
You can only apply one type of operation (add, deduct, or set) across all balances within a single row in the CSV. For example, if you’re updating both the points and gems balances in the same row and choose the add operation, both balances will be increased - you cannot add points and deduct gems in the same row.
However, you can apply different operations per user. For instance, you can add points and gems for one user and deduct them for another within the same CSV file. Below is an example of a CSV file that deducts points, gems, and diamonds from specific users.
### Additional Balance Configuration Options
When updating points, gems, or diamonds, the following options and rules apply:
* **Deduction options** *(optional, column `deduction_mode`)*: When deducting balances, the default behavior stops deductions at zero (`floor_to_zero`) to prevent negative balances. You can also require sufficient balance (`require_sufficient_balance`), which skips deduction for any user whose current balance is lower than the deduction amount.
* **Level synchronization** *(optional, column `sync_level`)*: When adjusting lifetime points, level recalculation can be enabled (`true`, default) or disabled (`false`).
* The import applies one `deduction_mode` and one `sync_level` value to a large group of rows at once, not to each row. Use the same value in every row of the file.
* **Non-negative values**: Balance values in the CSV must always be positive numbers (greater than or equal to 0). To deduct points or gems, specify `deduct` in the `operation_type` column rather than entering negative numbers.
### Upload ‘User Markers’ via CSV
You can **set** User Markers using a CSV import in Segments. This update also allows you to modify properties that accept array values.
{% hint style="warning" %}
**Important:** Uploading tags via CSV will completely overwrite any existing tags for a user. It is not possible to append new tags or remove specific ones using this method. If you need granular control over tags, please use the REST API.
{% endhint %}
BO: User markers in User profile page
**Required CSV Column -** `core_tags`
**Accepted Formats:**
* **\[ ]** - Sets empty value
* **\["text"]** - Sets a single user marker containing text.
* **\["text", "text1"]** - Sets multiple text-based user markers.
* **\["text", 10]** - Sets multiple user markers containing both text and numeric values.
* **\[10]** - Sets a numeric user marker.
* **\[10, 20]** - Sets multiple numeric user markers.
BO: Importing CSV segment with User markers
**⚠️ Important**: Updating markers via CSV import\
\
When updating markers using a CSV file, you can use either Excel / Google Sheets or a plain text editor (e.g. Notepad). However, there is an important difference in how these tools format the file.
* **Excel / Google Sheets** automatically add the required quotation marks and escape characters, so the file usually passes validation without extra work.
* **Plain text editors (like Notepad)** do not add this formatting for you. This means you must manually format the values correctly, otherwise the import will fail validation.
Required format for marker values (example):
```
core_tags:
"[""SMS TEST"", ""TEST ACCOUNT"", ""AFF TEAM"", ""CRM_TEAM_BASIC""]"
```
### Frequently Asked Questions
**Q: What is the maximum number of users that can be imported in a CSV segment?**
Smartico does not set a hard ceiling on the number of records in a CSV segment file. Large files containing hundreds of thousands of users are supported and are processed in batches in the background. The file itself can be at most 50 MB.
**Q: Does CSV import create new player accounts in Smartico?**
No. CSV segment import only matches against players who are already registered in Smartico. Unmatched user IDs are listed under the **Users in CSV** tab as **No matching users** and will not receive property updates.
**Q: Why do I get an error saying the `user_ext_id` column is missing even though it exists in my file?**
This error means that the first line of the file has no column named exactly `user_ext_id`. Most often the file uses an unsupported delimiter (for example, a tab), so the whole first line is read as one column name. Ensure the CSV file is saved in plain UTF-8 format using comma or semicolon delimiters, and that the first line holds the column names.
**Q: Can I append additional users to an existing CSV segment?**
Imported segments represent static snapshots created at the time of import. To target an updated list of users, create a new imported segment with your latest CSV file.
**Q: Can CSV segment membership be used immediately in marketing campaigns?**
Yes. As soon as the import status reaches Completed, the segment can be selected as the target audience in scheduled campaigns, automated journeys, and gamification rules.
---
# 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://help.smartico.ai/welcome/products/crm-automation/segmentation/imported-segments.md?ask=&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.
