File Import Status

Overview

The file import status API helps to fetch the processing status at both import and file levels. This helps in proactively tracking the status of the Imports and the Files in an import without navigating to the MoEngage dashboard. The following APIs allow you to fulfill this use case:

Import Details API
Import File Run History API

Use Cases

The ability to fetch the processing status of all imports for a given date range without navigating to the MoEngage dashboard.
The ability to proactively alert about failures in automated campaigns. For example, if an automated campaign must run using the updated list of users ingested into MoEngage through the import option, but if the import fails for any reason, it may impact the reachability of your campaigns. Typically, you become aware of import failure only when navigating to the MoEngage dashboard or when you receive an email alert. However, with this API, you can track the status proactively even before the campaign is impacted.

Import Details API

This API fetches the status at an import level. It can fetch the status of multiple imports but not the status of the files within the import.

API Endpoint

POST https://fileimports-data-api-{{0X}}.moengage.com/v1.0/data/fileimports/import/status

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.

info

Information

The APP_ID for your MoEngage account is available on the MoEngage dashboard. We've revamped our settings UI; you can find the APP_ID in the following navigations in the revamped and old UIs:

Revamped UI: Settings > Account > APIs / API keys > Workspace ID
Old UI: Settings > App Settings > Account Settings > APP ID

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

The username and password details can be obtained from the MoEngage dashboard. We've revamped the settings in the dashboard UI. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

Navigate to Settings -> Account -> APIs.
Click Generate Key in the Data tile in the API Keys section, and click Save.
Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

Navigate to Settings -> APIs -> DATA API Settings.
Click Generate Key.
Click Save on the Data APIs settings section.
Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Request Headers

Key

Mandatory/Optional

Sample Values

Description

Content-Type

Mandatory

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Mandatory

{"Authorization": "Basic bmF2ZWVuab mhDFhjdlbmdhZ2U=="}

This authentication parameter, used for access control, must be passed with the request. For more information on generating the authentication header, refer to Authentication.

MOE-APPKEY

Mandatory

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

The following sample request body describes fetching the import status for a given date range.

{
    "import_type": [
        "USERS",
        "EVENTS",
        "AUX_DATA"
    ],
    "date": {
        "start_date": "14/11/2024",
        "end_date": "14/11/2024",
        "format": "DD/MM/YYYY"
    },
    "schedule_type": [
        "PERIODIC",
        "ONETIME"
    ],
    "file_source": [
        "SFTP",
        "S3",
        "CSV"
    ],
    "schedule_status": [
        "SUCCESSFUL",
        "FAILED",
        "PARTIAL_SUCCESS",
        "SCHEDULED",
        "PROCESSING",
        "QUEUED",
        "ARCHIVED"
    ],
    "import_name": "{{import_name_of_the_respective_import}}"
    "offset": "1"
}

Request Body Fields

Key	Datatype	Mandatory	Description
import_type	String	No	This field denotes the type of data to be imported. Supported values are: USERS EVENTS AUX_DATA
date	Datetime	No	This field denotes the details of the import date. Supported values are: start_date end_date format If this field is not passed, the API will respond with the Import details for the last 7 days. Supported date time formats are: "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
schedule_type	String	No	This field denotes the type of import schedule. Supported values are: PERIODIC ONETIME
file_source	String	No	This field denotes the file source of the import. Supported values are: SFTP S3 CSV
schedule_status	String	No	This field denotes the import schedule status. Supported values are: SUCCESSFUL FAILED PARTIAL_SUCCESS (shown when all rows in the files are not processed successfully) SCHEDULED PROCESSING QUEUED (shows when the import is queued to be processed next) ARCHIVED (shows when the import is archived)
offset	String	No	API responds with a maximum of 50 import details in a single response. For example, if there are 150 imports in total, and they are part of the API response, then: Offset = 1 would fetch the details of the first 50 imports Offset = 2 would fetch the details of the next 50 imports Offset = 3 would fetch the details of the last 50 imports If offset is not passed in the request body, the API response will consider offset = 1. You can refer to the total_count parameter in the response to determine the total number of files in the response. OR If the API responds with more_files = true, it indicates that there are more files that are not part of the current response, for which another API request must be made with offset +1.

Response

Key	Datatype	Description
status	string	This field denotes the API Response status.
total_count	integer	This field denotes the total count of the imports in the response
data	JSON object	This field contains the import data details. For more information, refer to Data.
offset	string	This field denotes the pagination value of the imports. For example, if there are 100 imports to be fetched in the response, then: Offset = 1 will return the first 50 imports Offset = 2 will return the next 50 import details
more_files	string	This field indicates if there are more files. For example, if there are 100 imports and offset = 1, 50 imports will be returned with more_file = true to indicate that offset = 2 must be passed to get the next 50 imports.

Data

The data JSON object contains the following information:

Key	Datatype	Description
import_id	string	This field denotes the unique ID of the import.
import_name	string	This field denotes the unique name of the import.
last_run_status	string	This field denotes the latest sync status of the import.
import_type	string	This field denotes the import type. Supported values are: USERS EVENTS AUX_DATA
schedule_type	string	This field denotes the schedule type. Supported values are: ONETIME PERIODIC
import_source	string	This field denotes the source of import. Supported values are: S3 SFTP CSV
custom_segment_config	string	This field contains details about the custom segment. For more information, refer to Custom Segment Configuration.
aux_data_config	JSON object	This field contains details about the auxiliary data. For more information, refer to Auxiliary Data Configuration.
total_files	int	This field denotes the total number of files in the import.
processed_files	int	This field denotes the total number of processed files in the import.
total_rows	int	This field denotes the total number of rows across all files.
processed_rows	int	This field denotes the total number of processed rows across all files.
created_at	int	This field denotes the date at which the import is created.
last_run_at	datetime	This field denotes the date on which the import was last run.
next_scheduled_at	datetime	This field denotes the date on which the import is next scheduled.
created_by_email	string	This field denotes the email ID of the team member who created the import.
status	string	This field denotes the import status.
time_zone	string	This field denotes the timezone of the workspace.

Custom Segment Configuration

The custom-segment _config JSON object contains the following information:

Key	Datatype	Description
id	string	This field denotes the custom segment ID.
name	string	This field denotes the unique name of the custom event.
type	string	This field denotes the type of custom segment.
user_id_column	string	This field denotes the attribute selected as the identifier.

Auxiliary Data Configuration

The aux_data _config JSON object contains the following information:

Key

Datatype

Description

primary_key

string

This field denotes the attribute used as the auxiliary data import ID.

retention_period

int

This field denotes the number of days, weeks, and months (to be read with retention_type).

retention_type

string

The field denotes retention type. Supported values are:

DAYS
WEEKS
MONTHS

Response Codes

 {
    "status": "success",
    "total_count": 2,
    "data": [
        {
            "import_id": "67348ff2e15wwe63bc257d9bf",
            "import_name": "Special",
            "last_run_status": "FAILED",
            "import_type": "AUX_DATA",
            "schedule_type": "ONETIME",
            "import_source": "S3",
            "custom_segment_config": {},
            "aux_data_config": {
                "primary_key": "Email",
                "retention_period": 15,
                "retention_type": "DAYS"
            },
            "total_files": 0,
            "processed_files": 0,
            "total_rows": 0,
            "processed_rows": 0,
            "created_at": "2024-11-13T17:09:30.635000",
            "last_run_at": "2024-11-13T17:09:32.024000",
            "next_scheduled_at": "2024-11-13T11:39:30.619000",
            "created_by_email": "abc@moengage.com",
            "status": "FAILED",
            "time_zone": "Asia/Calcutta"
        },
        {
            "import_id": "67348f4a55f435b54f109i9",
            "import_name": "Duplicate_special",
            "last_run_status": "FAILED",
            "import_type": "AUX_DATA",
            "schedule_type": "ONETIME",
            "import_source": "S3",
            "custom_segment_config": {},
            "aux_data_config": {
                "primary_key": "Email",
                "retention_period": 15,
                "retention_type": "DAYS"
            },
            "total_files": 0,
            "processed_files": 0,
            "total_rows": 0,
            "processed_rows": 0,
            "created_at": "2024-11-13T17:06:42.722000",
            "last_run_at": "2024-11-13T17:06:44.182000",
            "next_scheduled_at": "2024-11-13T11:36:42.697000",
            "created_by_email": "abc@moengage.com",
            "status": "FAILED",
            "time_zone": "Asia/Calcutta"
        }
    ],
    "offset": 1,
    "more_files": false
}

Invalid or Mismatched date format passed
{
    "status": "FAILURE",
    "error_type": "Invalid Date format",
    "message": "The provided date format is either incorrect or doesn't 
      match the entered dates. Please ensure both the dates and the format are valid."
} 

      

Invalid bad request - Case sensitivity in parameter values passed in the API body 

{
    "success": false,
    "status_code": "400 Bad Request",
    "data": "Unable to process the request"
} 
      
 
Bad request - Incorrect offset value passed
{
    "status": "FAILURE",
    "error_type": "Invalid Offset Value",
    "message": "The offset value you have provided is not valid. Please review and correct the offset."
}
      

Bad request : Date range exceeds 30 days 
{
    "status": "FAILURE",
    "error_type": "Difference exceeds 30 days",
    "message": "Please note that only imports with a date difference of 30 can be displayed. Kindly adjust the dates accordingly."
}

MoeAPPkey missing, Invalid username, invalid password
      {
    "title": "HeaderMissing",
    "description": "MOE-APPKEY is missing in Header"
}

Invalid endpoint
      {
    "status": "fail",
    "data": "Resource not found"
}

Incorrect content type
{
    "title": "Unsupported media type",
    "description": "Content type is not supported"
}

Rate limit breach
{
    "status": "fail",
    "error": {
        "message": "Rate limits exceeded, please try after some time",
        "type": "Rate Limits Exceeded",
        "request_id": "1234"
    }
}

Sample cURL

The following sample cURL has all the filters passed in the API body.

curl --location 'https://fileimports-data-api-01.moengage.com/v1.0/data/fileimports/import/status' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
    "import_name": "test_import",
    "import_type": [
        "USERS",
        "EVENTS",
        "AUX_DATA"
    ],
    "date": {
        "start_date": "14/11/2024",
        "end_date": "14/11/2024",
        "format": "DD/MM/YYYY"
    },
    "schedule_type": [
        "PERIODIC",
        "ONETIME"
    ],
    "file_source": [
        "SFTP",
        "S3",
        "CSV"
    ],
    "schedule_status": [
        "SUCCESSFUL",
        "FAILED",
        "PARTIAL_SUCCESS",
        "SCHEDULED",
        "PROCESSING",
        "QUEUED",
        "ARCHIVED"
    ],
    "offset": "1"
}'
      
}

The following sample cURL has no filters passed in the API body. Note that the API response fetches all import details processed in the last 7 days.

curl --location 'https://fileimports-data-api-01.moengage.com/v1.0/data/fileimports/import/status' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
 
}'

Rate Limits

You can create 50 requests per minute.

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

Import File Run History API

This API fetches the file processing status of each file contained in an import. The API request must contain either the import _name or the import_id. If you are not sure of the import-id or the import_name, you can use the Import Details API to get the import details, which can be further used in the Import File Run History API.

API Endpoint

POST https://fileimports-data-api-{{0X}}.moengage.com/v1.0/data/fileimports/import/run/history

info

Information

The APP_ID for your MoEngage account is available on the MoEngage dashboard. We've revamped our settings UI; you can find the APP_ID in the following navigations in the revamped and old UIs:

Revamped UI: Settings > Account > APIs/API keys > Workspace ID
Old UI: Settings > App Settings > Account Settings > APP ID

Authentication

{"Authorization: Basic Base64_ENCODED_APPKEY_APIKEY=="}

Revamped UI

Navigate to Settings -> Account -> APIs.
Click Generate Key in the Data tile in the API Keys section, and click Save.
Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

Navigate to Settings -> APIs -> DATA API Settings.
Click Generate Key.
Click Save on the Data APIs settings section.
Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Request Headers

Key

Mandatory/Optional

Sample Values

Description

Content-Type

Mandatory

{"Content-Type": "application/json"}

Set the Content-Type header to application/json.

Authorization

Mandatory

{"Authorization": "Basic bmF2ZWVuab mhDFhjdlbmdhZ2U=="}

This authentication parameter, used for access control, must be passed with the request. For more information on generating the authentication header, refer to Authentication.

MOE-APPKEY

Mandatory

{“MOE-APPKEY”: “Workspace ID”}

This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage dashboard:

Settings -> Account -> APIs -> Workspace ID (earlier app id)

For more information, refer to Authentication.

Request Body

The following sample request body describes fetching the import status of files contained in an import named test_import.

{
    "import_id": "6735a04adba6bce02e720550",
    "created_at" : "2024-11-14T12:31:30.940000",
    "import_name": "test_import",
    "file_status": [
        "SUCCESSFUL",
        "FAILED",
        "PARTIAL_SUCCESS",
        "PROCESSING",
        "QUEUED",
        "WAITING"
    ],
    "offset": "1"
}

Request Body Fields

Key	Datatype	Mandatory Field	Description
import_id	String	Yes	The unique identifier is used to identify the import. You can find this on the Data Imports page of the MoEngage dashboard. Data > Data Imports > Click the ellipsis icon for an import > View. The import_id or the import_name must be passed.
import_name	String	Yes	This field denotes the name of the import. The import_id or import_name has to be passed. If both are passed, import_id takes precedence.
created_at	Datetime	No	This field denotes the time at which the import is created. Supported date time formats are: "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
file_status	String	No	This field denotes the status of files contained in an import. Supported values are: SUCCESSFUL FAILED PARTIAL_SUCCESS PROCESSING QUEUED WAITING
offset	String	No	API responds with a maximum of 50 file details in a single response. For example, if there are a total of 150 files that are part of the API response, then: Offset = 1 will fetch the details of the first 50 files Offset = 2 will fetch the file details of the next 50 imports Offset = 3 will fetch the import details of the last 50 imports If offset is not passed in the request body, the API response will consider offset = 1. You can refer to the total_count parameter in the response to understand how many total files are part of the response. OR If the API responds with more_files = true, it indicates that there are more files that are not part of the current response for which another API request must be made with offset +1.

Response

Key	Datatype	Description
status	string	This field denotes the status of the API response.
total_count	integer	This field denotes the total count of the files fetched based on the API request.
data	JSON object	This field contains the file data details. For more information, refer to Data.
offset	string	This field denotes the pagination value of the imports. For example, if there are 100 imports to be fetched in the response: Offset = 1 will return the first 50 imports Offset = 2 will return the next 50 import details
more_files	string	This field indicates if there are more files. For example, if there are 100 imports and offset = 1, 50 imports will be returned with more_file = true to indicate that offset = 2 must be passed to get the next 50 imports.

Data

The data JSON object contains the following information:

Key	Datatype	Description
id	string	This field denotes the unique ID of the file.
file_name	string	This field denotes the name of the file.
scheduled_at	datetime	This field denotes the time at which the file is scheduled.
completed_at	datetime	This field denotes the time at which the file is completed.
type	string	This field denotes the file type. Supported values are: USERS EVENTS AUX_DATA
file_size	integer	This field denotes the file size in terms of the number of rows in the file.
file_status	string	This field denotes the file status. Supported values are: SUCCESSFUL FAILED, PARTIAL_FAILURE QUEUED
status_msg	string	This field denotes the error message in case of failure or partial failure.
total_rows	integer	This field denotes the total number of rows in the file.
skipped_rows	integer	This field denotes the skipped number of rows in the file.
updated_rows	integer	This field denotes the updated number of rows in the file.
failed_rows	integer	This field denotes the number of rows in the file that failed to process.
aux_data_added_count	integer	This field denotes the number of rows added as auxiliary data. This is applicable to auxiliary data.
aux_data_failed_count	integer	This field denotes the number of rows that failed to process. This is applicable to auxiliary data.
added_rows	integer	This field denotes the total number of rows added from the file.

Response Codes

 {
    "status": "success",
    "total_count": 1,
    "data": [
        {
            "id": "672561rr0abd2da34cf7f7df",
            "file_name": "filename.csv",
            "scheduled_at": "2024-11-14T12:31:31.713000",
            "completed_at": "2024-11-14T12:32:09.942000",
            "type": "AUX_DATA",
            "file_size": "1544",
            "file_status": "SUCCESSFUL",
            "status_msg": "",
            "total_rows": 10,
            "skipped_rows": 0,
            "updated_rows": 0,
            "failed_rows": 0,
            "aux_data_added_count": 10,
            "aux_data_failed_count": 0,
            "added_rows": 10
        }
    ],
    "offset": 1,
    "more_files": false
}


Bad request 
{
    "status": "FAILURE",
    "error_type": "Import Doesn't Exist",
    "message": "No import exist in the database with the given query parameters."
}
      

Date range not in ISO format
{
    "status": "FAILURE",
    "error_type": "Invalid Date format",
    "message": "The date entered is not in the correct format. Please ensure you are using the ISO 8601 format which should look like this: YYYY-MM-DDTHH:MM:SS.ssssss. Please check this and try again."
}
      

Incorrect offset value passed
{
    "status": "FAILURE",
    "error_type": "Import Doesn't Exist",
    "message": "No import exist in the database with the given query parameters."
}

Appkey missing
      {
    "title": "HeaderMissing",
    "description": "MOE-APPKEY is missing in Header"
}

 Invalid endpoint 
      { "status": "fail", "data": "Resource not found" }

Content mismatch
      {
    "title": "Unsupported media type",
    "description": "Content type is not supported"
}

Rate limit breach
  {
    "status": "fail",
    "error": {
        "message": "Rate limits exceeded, please try after some time",
        "type": "Rate Limits Exceeded",
        "request_id": "1234"
    }
  }

Sample cURL

The following sample cURL has import_name and import_id, which are passed in the API body. Note that it is mandatory to pass the import_name or the import_id to the API body.

curl --location 'https://fileimports-data-api-01.moengage.com/v1.0/data/fileimports/import/run/history' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data '{
    "import_id": "6735a04adba6bce02e720550",
    "import_name": "test_import",
    "created_at" : "2024-11-14T12:31:30.940000",
    "import_name": "test_import",
    "file_status": [
        "SUCCESSFUL",
        "FAILED",
        "PARTIAL_SUCCESS",
        "PROCESSING",
        "QUEUED",
        "WAITING"
    ],
    "offset": "1"
}'

Rate Limits

You can create 50 requests per minute.

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.