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

# Overview - Imports

> Get started with MoEngage data imports. Compare sources, see which entity types each supports, and choose the right import path for users, events, and auxiliary data.

# Introduction

MoEngage lets you import users, events, and auxiliary data into your workspace from files (Amazon S3, SFTP, or a manual CSV upload) and directly from your data warehouse (Snowflake, BigQuery, or Databricks). This page helps you choose the right source for your use case. Once you pick a path, its dedicated setup page walks you through the entire process.

<Info>
  If your system requires IP whitelisting, refer to [IP Whitelisting in MoEngage](/docs/user-guide/settings/account/security/ip-whitelisting-in-moengage) before setting up a data import.
</Info>

# Sources and Supported Entities

Each source supports a different set of entity types. Use this matrix to confirm your source can import the data you need.

**File Sources**

| Source              | Registered Users | Anonymous Users | Events | Auxiliary Data |
| ------------------- | :--------------: | :-------------: | :----: | :------------: |
| Amazon S3           |         ✅        |        ✅        |    ✅   |        ✅       |
| SFTP                |         ✅        |        ✅        |    ✅   |        ✅       |
| Manual Upload (CSV) |         ✅        |        ✅        |    ✅   |        ✅       |

**Data Warehouses**

| Source     | Registered Users | Anonymous Users | Events | Auxiliary Data |
| ---------- | :--------------: | :-------------: | :----: | :------------: |
| Snowflake  |         ✅        |        ✅        |    ✅   |        ❌       |
| BigQuery   |         ✅        |        ✅        |    ✅   |        ❌       |
| Databricks |         ✅        |        ✅        |    ✅   |        ❌       |

**Entity types:**

* **Registered Users**: Users already registered on MoEngage. Also used to update existing users in bulk.
* **Anonymous Users**: Users who have not yet registered on MoEngage.
* **Events** (Standard and User-Defined): Standard events such as Campaign Interaction Events, as well as your own user-defined events.
* **Auxiliary Data**: User data ingested into MoEngage temporarily for specific business purposes. Available for file-based sources only (S3, SFTP, and Manual Upload), not for data warehouses.

# Choose Your Import Path

Select the import method that matches where your data lives:

<CardGroup cols={2}>
  <Card title="Set Up a File Import" href="/docs/user-guide/data/imports/setting-up-a-file-import" icon="folder">
    Automate imports from files dropped in Amazon S3 or an SFTP server, on a one-time or periodic schedule.
  </Card>

  <Card title="Set Up a Data Warehouse Import" href="/docs/user-guide/data/imports/setting-up-a-data-warehouse-import" icon="database">
    Import directly from Snowflake, BigQuery, or Databricks tables and views. Connection-driven, with one-time or periodic syncs.
  </Card>

  <Card title="Manual Uploads" href="/docs/user-guide/data/imports/manual-uploads" icon="upload">
    Upload a CSV directly in the dashboard for users or events. One-time only, no periodic scheduling.
  </Card>

  <Card title="Auxiliary Data" href="/docs/user-guide/data/imports/auxiliary-data" icon="table">
    Import supplementary data via S3, SFTP, or CSV, using a simple primary-key mapping model.
  </Card>
</CardGroup>

# How Imports Work

The following mechanics are common to every import source. Source-specific setup steps, limits, and failure behavior live on each source's setup page.

## Imports Dashboard

The Data Imports dashboard lists all your imports and their key details:

| **Column**           | **Description**                                                                                                                            |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Name**             | The name you gave the import while setting it up.                                                                                          |
| **Type**             | The source of the import (S3, SFTP, CSV, Snowflake, BigQuery, or Databricks). The import type, One-Time or Periodic, is shown in brackets. |
| **Custom Segment**   | If the user import saves to a segment, the segment name is displayed here.                                                                 |
| **Created at**       | The date and time the import was created.                                                                                                  |
| **Last Sync Status** | The latest status of the import (see statuses below).                                                                                      |
| **Files Processed**  | The number of files processed to date.                                                                                                     |
| **Rows Processed**   | The total number of rows processed to date.                                                                                                |
| **Actions**          | View Details, Edit, Duplicate, or Delete an import.                                                                                        |

<Info>
  Import schedule and detail times shown on the Data Imports dashboard use your app's configured timezone. If no app timezone is set, they display in UTC by default. Set the app timezone from **Settings** to see these times in your preferred timezone. This display timezone is separate from the requirement that mapped timestamp columns (such as **Event time** or **Updated at**) always be in UTC.
</Info>

## Import Statuses

Every import on the dashboard carries one of the following statuses:

* **Scheduled**: The import is scheduled to run in the future.
* **Processing**: The import is currently running.
* **Successful**: The import completed successfully.
* **Partial Success**: At least one file (or row) was imported with partial success.
* **Failed**: The import failed. Hover over the status to see the reason.

To see per-file details, rows in file, users created/updated/failed, events added/failed, aux data added/failed, and rows skipped, open the three-dot Actions menu and select **View Details**. You can export a copy of an imported file for up to 60 days.

## Trigger Imports

You can trigger imports in the following ways:

1. **Manually**: Trigger a periodic import from the imports page by clicking **Actions**. Triggering an import within five minutes of its scheduled time may cause an error.
2. **API**: Trigger imports using the [File Imports Trigger API](https://www.moengage.com/docs/api/file-import/trigger-file-imports). Data Warehouses do not currently support these APIs.

# Mapping Files and Data Mapping

A mapping file contains the mappings between each source column and a MoEngage attribute, along with the data type of the column. The file must be in JSON format. Instead of mapping columns one by one on the dashboard, you can upload a mapping file to automate the mapping.

<Tabs>
  <Tab title="CSV Files">
    ```json theme={null}
    {
      "mapping": [
        { "column": "ID", "moe_attr": "uid", "type": "string", "is_skipped": false },
        { "column": "First Name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
        { "column": "First Seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
        { "column": "LTV", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
        { "column": "Install Status", "moe_attr": "installed", "type": "bool", "is_skipped": false }
      ]
    }
    ```
  </Tab>

  <Tab title="JSON Files">
    ```json theme={null}
    {
      "mapping": [
        { "column": "customer_id", "moe_attr": "uid", "type": "string", "is_skipped": false },
        { "column": "user.first_name", "moe_attr": "u_fn", "type": "string", "is_skipped": false },
        { "column": "user.first_seen", "moe_attr": "cr_t", "type": "datetime", "datetime_format": "YYYY-MM-DD hh:mm:ss", "is_skipped": false },
        { "column": "attribution.lifetime_value", "moe_attr": "t_rev", "type": "double", "is_skipped": false },
        { "column": "attribution.device_installed", "moe_attr": "installed", "type": "bool", "is_skipped": false }
      ]
    }
    ```
  </Tab>
</Tabs>

For each column, provide the following fields:

1. **`column`** *(required)*: The column name from the source file. For Level 2 keys in a JSON file, use dot notation (`key1.key2`).
2. **`moe_attr`** *(required)*: The MoEngage attribute to map the column to. Ensure each column maps to a unique `moe_attr`.
3. **`type`** *(optional)*: The data type of the column. See the supported types below.
4. **`datetime_format`** *(optional)*: The date-time format. Mandatory for DateTime fields only.
5. **`is_skipped`** *(optional)*: A boolean field. Any column marked `true` is skipped during import.

### Standard User Attributes for Reference

Map your source columns to MoEngage standard user attributes using the keys below. For the exhaustive list, refer to your [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard.

| Key                | Attribute Name on Dashboard | Datatype             | Description                                                                                                            |
| :----------------- | :-------------------------- | :------------------- | :--------------------------------------------------------------------------------------------------------------------- |
| `uid`              | ID                          | String               | Unique ID that the app has set for a user.                                                                             |
| `u_n`              | Name                        | String               | Full name of the user.                                                                                                 |
| `u_fn`             | First Name                  | String               | First name of the user.                                                                                                |
| `u_ln`             | Last Name                   | String               | Last name of the user.                                                                                                 |
| `u_em`             | Email (Standard)            | String               | The email address of the user. For example, `john@example.com`.                                                        |
| `u_gd`             | Gender                      | String               | Gender of the user.                                                                                                    |
| `u_bd`             | Birthday                    | DateTime             | Birth date of the user. Use this standard attribute instead of age; data sent as age is tracked as a custom attribute. |
| `u_mb`             | Mobile Number (Standard)    | String               | Mobile number of the user. For example, `918888444411`.                                                                |
| `moe_geo_location` | Location                    | Array of `[lat,lng]` | The location of the user, in the format `{"lat": 12.11, "lon": 123.122}`.                                              |
| `source`           | Publisher Name              | String               | The publisher name of the install. For example, `Google Ads`.                                                          |
| `revenue`          | LTV                         | Numeric              | Lifetime value of the user.                                                                                            |
| `moe_unsubscribe`  | Unsubscribe                 | Boolean              | Email unsubscribe attribute. Emails are not sent to the user when set to `true`.                                       |
| `moe_hard_bounce`  | Hard Bounce                 | Boolean              | Email hard bounce attribute. Emails are not sent to the user when set to `true`.                                       |
| `moe_spam`         | Spam                        | Boolean              | Email spam attribute. Emails are not sent to the user when set to `true`.                                              |

<Warning>
  Track standard string attributes with the correct data type. For example, if **First Name** (`u_fn`) is ingested as a number or an array instead of a string, the sample users on the [Create segment](/docs/user-guide/segment/create-segments/rule-based-filter-segments) page fail to load with a 500 error ("There seems to be an error"). To fix this, pin the attribute's data type to String on the [Data Management](/docs/user-guide/settings/data-management/overview-data-management) dashboard and re-send the corrected data for the affected users.
</Warning>

### Supported Attribute Types

| **Type**  | **Description**                                                | **Value in Mapping File** |
| --------- | -------------------------------------------------------------- | ------------------------- |
| String    | Any string value. For example, `ABC`, `ABC XYZ`, `ABC123`.     | `"type": "string"`        |
| Double    | Any decimal value. For example, `3.14159`, `241.23`, `-123.1`. | `"type": "double"`        |
| Boolean   | For example, `true`, `false`.                                  | `"type": "bool"`          |
| Date Time | Any date-time value. For example, `2019/02/22 17:54:14.933`.   | `"type": "datetime"`      |

<Info>
  MoEngage does not support the `|` (pipe) character in non-array type columns. Ensure your String, Numeric, and Boolean columns do not contain this character.
</Info>

### Reserved Keywords for User Attributes

MoEngage reserves the following keys. Do not use them when you map or track user attributes.

* `USER_ATTRIBUTE_UNIQUE_ID`
* `USER_ATTRIBUTE_USER_EMAIL`
* `USER_ATTRIBUTE_USER_MOBILE`
* `USER_ATTRIBUTE_USER_NAME`
* `USER_ATTRIBUTE_USER_GENDER`
* `USER_ATTRIBUTE_USER_FIRST_NAME`
* `USER_ATTRIBUTE_USER_LAST_NAME`
* `USER_ATTRIBUTE_USER_BDAY`
* `USER_ATTRIBUTE_NOTIFICATION_PREF`
* `USER_ATTRIBUTE_OLD_ID`
* `MOE_TIME_FORMAT`
* `MOE_TIME_TIMEZONE`
* `USER_ATTRIBUTE_DND_START_TIME`
* `USER_ATTRIBUTE_DND_END_TIME`
* `MOE_GAID`
* `INSTALL`
* `UPDATE`
* `MOE_ISLAT`
* `status`
* `user_id`
* `source`

# Supported Datetime Formats

Use these formats in the `datetime_format` field of your mapping file, or when configuring date-time columns during setup.

| **Datetime Format**                             | **Examples**                                                                                                                 |
| ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `"datetime_format": "YYYY-MM-DD"`               | 2022-01-22                                                                                                                   |
| `"datetime_format": "YYYY/MM/DD"`               | 2022/01/22                                                                                                                   |
| `"datetime_format": "DD/MM/YYYY"`               | 22/01/2022                                                                                                                   |
| `"datetime_format": "DD-MM-YYYY"`               | 22-01-2022                                                                                                                   |
| `"datetime_format": "DD-MM-YYYY hh:mm:ss"`      | 31-12-2022 12:10:33                                                                                                          |
| `"datetime_format": "DD/MM/YYYY hh:mm:ss"`      | 31/12/2022 12:10:33                                                                                                          |
| `"datetime_format": "YYYY-MM-DD hh:mm:ss"`      | 2019-02-22 17:54:14                                                                                                          |
| `"datetime_format": "YYYY/MM/DD hh:mm:ss"`      | 2019/02/22 17:54:14                                                                                                          |
| `"datetime_format": "DD-MM-YYYYThh:mm:ss.s"`    | 31-12-2022T12:10:33.882                                                                                                      |
| `"datetime_format": "DD/MM/YYYYThh:mm:ss.s"`    | 31/12/2022T12:10:33.882                                                                                                      |
| `"datetime_format": "DD-MM-YYYYThh:mm:ssTZD"`   | <ul><li>31-12-2022T12:10:33Z</li><li>31-12-2022T12:10:33+08:00</li><li>31-12-2022T12:10:33-08:00</li></ul>                   |
| `"datetime_format": "DD/MM/YYYYThh:mm:ssTZD"`   | <ul><li>31/12/2022T12:10:33Z</li><li>31/12/2022T12:10:33+08:00</li><li>31/12/2022T12:10:33-08:00</li></ul>                   |
| `"datetime_format": "YYYY-MM-DD hh:mm:ss.s"`    | 2019-02-22 17:54:14.933                                                                                                      |
| `"datetime_format": "YYYY/MM/DD hh:mm:ss.s"`    | 2019/02/22 17:54:14.933                                                                                                      |
| `"datetime_format": "YYYY-MM-DDThh:mm:ssTZD"`   | <ul><li>2019-11-14T00:01:02Z</li><li>2019-11-14T00:01:02+08:00</li><li>2019-11-14T00:01:02-08:00</li></ul>                   |
| `"datetime_format": "YYYY/MM/DDThh:mm:ssTZD"`   | <ul><li>2019/11/14T00:01:02Z</li><li>2019/11/14T00:01:02+08:00</li><li>2019/11/14T00:01:02-08:00</li></ul>                   |
| `"datetime_format": "YYYY-MM-DDThh:mm:ss.sTZD"` | <ul><li>2019-02-22T17:54:14.957Z</li><li>2019-02-22T17:54:14.957299-08:00</li><li>2019-02-22T17:54:14.957299+08:00</li></ul> |
| `"datetime_format": "YYYY/MM/DDThh:mm:ss.sTZD"` | <ul><li>2019/02/22T17:54:14.957Z</li><li>2019/02/22T17:54:14.957299-08:00</li><li>2019/02/22T17:54:14.957299+08:00</li></ul> |

# Frequently Asked Questions

<Accordion title="My imports have failed. How do I check what went wrong?">
  Click the ellipsis on the right and click **View** to look up the Import details. Hover over the **Failed** Status to learn the reason.
</Accordion>

<Accordion title="What if a scheduled import adds the data into a recently archived segment?">
  In such cases, the new data will still be added to the archived segment. You can unarchive the segment as required.
</Accordion>

<Accordion title="Can an import be stopped while it's running?">
  Once an import process starts, it can't be stopped midway. This is because the data goes through several steps, and interrupting it could lead to incomplete or inconsistent results. It's best to let the current import finish.
</Accordion>

<Accordion title="How can I stop future runs of a scheduled import?">
  Yes, you can stop future scheduled imports from running automatically. To do this, find the import schedule and select the **Archive** option from the Actions menu on the Data Imports dashboard. This will prevent it from running on its next scheduled time.
</Accordion>

<Accordion title="What should I do if an import seems stuck or is taking a long time?">
  If an import appears to be stuck or is taking longer than usual, it's best to wait. The system has checks in place to handle these situations automatically and retry if necessary. Manually starting the same import again while it's still processing can cause conflicts and may prevent the original import from completing successfully.
</Accordion>