> ## Documentation Index
> Fetch the complete documentation index at: https://help.maestra.io/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Bulk Import Customers from a File

Prepare a file in the right format and upload it to add customers to your account.

Need to add customers with a specific action template, at a particular touchpoint, into a segment, or with a past date? Use the [advanced settings](#step-4-configure-the-import).

Imports run under **Customer Data Platform → Imports**. Click **New import** to open the settings.

## Step 1. Choose the import type

* Pick the import type — **Customers**.
* Pick the action:
  * **Add new customers** — loads only customers who aren't in the database yet. Existing customers aren't edited.
  * **Add and edit** — loads new customers and updates existing ones.

> [!WARNING]
>
> If a customer with the identifier you pass already exists, **Add and edit** overwrites their data.

## Step 2. Prepare and upload the file

Work out which fields you need. The file has to contain every required field.

> [!NOTE]
>
> The file needs at least one customer identifier: email, phone, or an external ID. All other fields are optional.

**Fields you can load:**

| Field | Description |
| - | - |
| `Email` | Email address |
| `IsEmailConfirmed` | Whether the email is [confirmed](https://help.maestra.io/customers-orders-and-products/customers/contacts-and-identifiers/contact-confirmation/contact-confirmation-status.md), as true/false |
| `MobilePhone` | Mobile phone |
| `IsMobilePhoneConfirmed` | Whether the mobile phone is [confirmed](https://help.maestra.io/customers-orders-and-products/customers/contacts-and-identifiers/contact-confirmation/contact-confirmation-status.md), as true/false |
| `DiscountCard` | [Discount card](https://help.maestra.io/loyalty/discount-cards/how-to-bulk-import-discount-cards.md) number |
| `Area` | The customer's area ID |
| `LastName` | Last name |
| `FirstName` | [First name](https://help.maestra.io/customers-orders-and-products/customers/personal-data/how-customer-names-are-cleaned-up.md) |
| `MiddleName` | [Middle name](https://help.maestra.io/customers-orders-and-products/customers/personal-data/how-customer-names-are-cleaned-up.md) |
| `FullName` | [Full name](https://help.maestra.io/customers-orders-and-products/customers/personal-data/how-customer-names-are-cleaned-up.md) |
| `Sex` | [Gender](https://help.maestra.io/customers-orders-and-products/customers/personal-data/how-customer-gender-is-determined-from-name.md) |
| `BirthDate` | Date of birth |
| `IsSubscribed` | [Global subscription](https://help.maestra.io/customers-orders-and-products/customers/subscriptions/how-customer-subscriptions-work.md), as true/false |
| `IsSubscribedByEmail`, `IsSubscribedBySms`, `IsSubscribedByViber`, `IsSubscribedByMobilePush`, `IsSubscribedByWebPush` | Subscription at the touchpoint in the Email, SMS, Viber, MobilePush, or WebPush channel, as true/false |
| `IsSubscribedByEmailOnNews` | Mailing topic subscription at the touchpoint in the Email, SMS, Viber, MobilePush, or WebPush channel, as true/false (one column per topic and channel) |
| Custom fields | Any custom fields created in your account |

> [!NOTE]
>
> **Multi-brand accounts:** if your account uses [multi-brand](https://help.maestra.io/administration/multibrand.md), the global, channel, and topic subscription columns apply within the brand of the touchpoint. See [How to subscribe customers to a brand](#how-to-subscribe-customers-to-a-brand).

Export the data from another system if you need to.

Build the file. Use the first row for the names of the fields you're loading — the wording is up to you.

* Format: `.csv` or `.txt`.
* Check that the values match the allowed formats.

Here's an example of a file ready for import:

![Example customer import file](https://mintcdn.com/maestraio/Itk5DZRmZl9Vbe7N/images/imported/img-d1b6ebe0.png?fit=max\&auto=format\&n=Itk5DZRmZl9Vbe7N\&q=85\&s=96845fd5386f32ec453ff9fcfb5fbf05)

See [Preparing a file for import](https://help.maestra.io/import-data/preparing-a-file-for-import.md) for the full set of recommendations.

Upload the file and click **Continue**.

## Step 3. Map the file's fields

Maestra Platform maps the file's columns to its own fields automatically. Check the result and adjust it by hand if you need to:

* In the **Import** column, tick the fields you want to load. Unticked columns are skipped.
* In the **Maestra field** column, map each file column to a field on the account. Optional fields left unmapped are skipped.

> [!TIP]
>
> If a custom field you need doesn't exist yet, create it with the **Create custom field** button.

Click **Continue**.

## Step 4. Configure the import

This step sets extra parameters for the import action:

* **Data source** — the integration point the data came through. Affects how the customer's actions are attributed. Defaults to the Maestra admin panel.
* **Segment** — a static segment every customer in the file is added to.
* **Customer action** — whether to issue an action when the customer is created. Defaults to **Issue**.
* **Comment** — a description of the import. Makes it easier to find in the list later.

### Set an action template

> [!NOTE]
>
> Accounts created after September 24, 2026 don't get an action when a customer is created, so the **Configure customer action** block isn't available. If you're not sure when your account was created, check with your account manager.

When **Customer action** is set to **Issue**, fill in the **Configure customer action** block:

* **Source action** — the action the customer enters the database with. Affects segmentation and analytics.
* **Touchpoint** — the channel or integration the action is tied to. Defaults to detecting it automatically from the integration point. To tie customers to a specific website or store, pick the touchpoint manually.

If the [action template](https://help.maestra.io/customers-orders-and-products/actions/action-template/how-to-create-an-action-template.md) you need doesn't exist yet, create it in advance or from the link on the import page. Pick its categories based on your business goal.

You can set the template in two ways:

* **Every customer in the file has the same template** — pick the action in the settings.
* **Customers in the file have different templates** — add the template's system name to the file:

  * for the source action, in the column with the system name of the action the customer entered the database with;
  * for the edit action, in the column with the system name of the personal action for the customer's last update.

  Then tick **Take value from import file** in the settings.

> [!NOTE]
>
> You can only set the edit action in the file, and only with a template in the **Personal action** category. Otherwise, changes to the customer are saved without recording an action.

### Set a touchpoint

If the [touchpoint](https://help.maestra.io/customers-orders-and-products/actions/channels-and-touchpoints/touchpoints/how-to-create-a-touchpoint.md) you need doesn't exist yet, create it in advance or from the link on the import page.

You can set the touchpoint in two ways:

* **Every customer in the file has the same touchpoint** — pick the integration point with the touchpoint you need, or set the touchpoint explicitly in the settings.
* **Customers in the file have different touchpoints** — add the touchpoints' external IDs to the file:

  * for the source action, in the column with the touchpoint external ID for the source action;
  * for the edit action, in the column with the external ID of the touchpoint where the customer was last changed.

  Then tick **Take value from file** in the settings.

### How to subscribe customers to a brand

On a multi-brand account, the integration point's brand sets the brand of the customer's subscription. The subscription is passed through the global subscription, channel subscription, and topic subscription columns.

To subscribe customers to several brands at once, run the import again for each brand.

**1. Find your brand's integration point**

Go to the **Integrations** section.

**2. Pick the integration point for the import**

Filter by brand and pick an integration point. For example, to subscribe customers to the Demo brand's campaigns, use that brand's website integration point.

**3. Select that integration point in Step 4. Configure the import**

### Add to a segment

Pick a static segment. If there's no suitable one yet, [create a new one](https://help.maestra.io/segments/how-to-create-a-static-customer-segment.md).

### Use a different time

There's no separate time setting. To set the time, add these columns to the file:

* for the source action, the date the customer entered the database, in UTC;
* for the edit action, the date the customer was last updated, in UTC.

If you leave these columns out, the actions are recorded at the time the import task runs.

## Step 5. Review and start the import

Before you start, Maestra Platform shows the first rows of the file with the mapping already applied. Check that the data looks the way you expect — that the right values landed in the right fields.

If everything's correct, click **Start import**.

## How to track the import

Once started, the import appears in the list on the **Import** page. For each task you'll see:

* start date,
* import type,
* source file with its comment,
* load progress,
* rows imported and errors,
* who started it.

If errors came up during the import, some rows were skipped. Open the import details to see which rows had a problem and why. Fix them in the file and run the import again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.