Bulk Import

Overview

Use the Bulk Import API to send, to MoEngage, in batch multiple user and event requests using a single API request. You can send a batch request of a maximum of 100 kB in a single API call.

API Endpoint

URL
POST https://api-0X.moengage.com/v1/transition/<APP_ID>

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

Note

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 -> App 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 bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

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

Revamped UI

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

Old UI

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

Request Parameters

Key Mandatory/Optional Data String Description

app_id

Mandatory

String

This is your MoEngage account's APP ID that has to be passed along with the request. You can find your MoEngage APP ID in the following navigation on the Dashboard:

Revamped UI: Settings > Account > APIs > App ID

Old UI: Settings > API > General Settings > DATA API

 

Request Headers

Key Mandatory/Optional Sample Values Description

X-Forwarded-For

Mandatory

Header Value Format: <IP Address>

The 'X-Forwarded-For' header is used to specify the IP address of the client that made the request. This header may be added by proxy servers or load balancers. The header value must contain the IP address of the original client that initiated the request. Multiple IP addresses may be specified in the header value, separated by commas. (This is optional)

Content-Type

Mandatory

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

Set the Content-Type header to application/json.

Authorization

Mandatory

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

 

Request Body

Request Body Fields

Key Datatype Required Description
type String Yes

This is used to identify the type of request.

Allowed Value: transition

Example: "type": "transition"

Note: This field is case-sensitive. Follow the case as in the example when passing the value in the request.

elements List Yes

List of data points (events and customers) to track.

Note: The type field in this List denotes whether the information is for a customer or an event. This field is case-sensitive. Follow the case as in the example when passing the value in the request.

  • Allowed Values: customer, event
  • Examples: "type": "customer", "type": "event"
info

Note

All bulk API requests return a 200 response code. Debugging should be done on the user profile on the dashboard.

Example Payload

A sample API request is as follows:

JSON
{
    "type":"transition",
    "elements":[
        {
            "type":"customer",
            "customer_id":"john@example.com",
            "attributes":{
                "name":"John",
                "platforms":[
                    {
                        "platform":"ANDROID",
                        "active":"true"
                    }
                ]
            }
        },
        {
            "type":"event",
            "customer_id":"john@example.com",
            "device_id":"96bd03b6-defc-4203-83d3-dc1c73080232",
            "actions":[
                {
                    "action":"Added to Cart",
                    "attributes":{
                        "product":"Mobile",
                        "color":"white",
                        "Brand":"Apple"
                    },
                    "platform":"iOS",
                    "app_version":"1.2.3",
                    "current_time":"2020-05-31T16:33:35Z",
                    "user_timezone_offset":19800
                },
                {
                    "action":"Purchase",
                    "attributes":{
                        "product":"MacBook Air",
                        "Brand":"Apple"
                    },
                    "platform":"iOS",
                    "app_version":"1.2.3",
                    "current_time":1590404615,
                    "user_timezone_offset":19800
                }
            ]
        }
    ]
}

 

Response Codes

200 400

Success Response
{ "status": "success", "message": "Your request has been accepted and will be processed soon." }

 

Sample cURL Request

cURL
curl --location 'https://api-01.moengage.com/v1/transition/VJ0GSMESHMQA3L7WV1EEK3UR?app_id=VJ0GSMESHMQA3L7WV1EEK3UR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VkowR1NNRVNITVFBM0w3V1YxRUVLM1VSOkZJd0N5dGZ0QWpZcl9tcVlldkVPVkFtbw==' \
--data '{
    "type": "transition",
    "elements": [
        {
            "type": "customer",
            "customer_id": "AZ8TM",
            "attributes": {
                "name": "qjDKn",
                "first_name": "xSEdd",
                "last_name": "UWbah",
                "platforms": [
                    {
                        "platform": "iOS",
                        "active": "true"
                    }
                ]
            }
        },
        {
            "type": "customer",
            "customer_id": "9yt8q8",
            "attributes": {
                "name": "5Np",
                "first_name": "2irjN",
                "last_name": "CH4Zo",
                "platforms": [
                    {
                        "platform": "ANDROID",
                        "active": "true"
                    }
                ]
            }
        },
        {
            "type": "customer",
            "customer_id": "ONfYcF",
            "attributes": {
                "name": "U92",
                "first_name": "zgI63",
                "last_name": "Dle4b",
                "platforms": [
                    {
                        "platform": "web",
                        "active": "true"
                    }
                ]
            }
        },
        {
            "type": "device",
            "customer_id": "AZ8TM",
            "device_id": "AZ8TM",
            "attributes": {
                "brand": "{{model_bulk1}}",
                "platform": "{{platform_bulk1}}",
                "push_id": "pushid1991"
            }
        },
        {
            "type": "device",
            "customer_id": "9yt8q8",
            "device_id": "9yt8q8",
            "attributes": {
                "brand": "{{model_bulk1}}",
                "platform": "{{platform_bulk1}}",
                "push_id": "pushid2744"
            }
        },
        {
            "type": "device",
            "customer_id": "ONfYcF",
            "device_id": "ONfYcF",
            "attributes": {
                "brand": "{{model_bulk1}}",
                "platform": "{{platform_bulk1}}",
                "push_id": "pushid3546"
            }
        },
        {
            "type": "event",
            "customer_id": "AZ8TM",
            "actions": [
                {
                    "action": "A6CO5",
                    "attributes": {
                        "product": "Shirt"
                    },
                    "platform": "{{platform_bulk1}}",
                    "app_version": "839",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                },
                {
                    "action": "wuDX8",
                    "attributes": {
                        "product": "MacBook Air",
                        "Brand": "Apple"
                    },
                    "platform": "iOS",
                    "app_version": "1.2.3",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                }
            ]
        },
        {
            "type": "event",
            "customer_id": "9yt8q8",
            "actions": [
                {
                    "action": "A6CO5",
                    "attributes": {
                        "product": "Shirt"
                    },
                    "platform": "{{platform_bulk1}}",
                    "app_version": "1.2.3",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                },
                {
                    "action": "Purchase",
                    "attributes": {
                        "product": "MacBook Air",
                        "Brand": "Apple"
                    },
                    "platform": "iOS",
                    "app_version": "1.2.3",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                }
            ]
        },
        {
            "type": "event",
            "customer_id": "ONfYcF",
            "actions": [
                {
                    "action": "A6CO5",
                    "attributes": {
                        "product": "Shirt"
                    },
                    "platform": "{{platform_bulk1}}",
                    "app_version": "1.2.3",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                },
                {
                    "action": "Purchase",
                    "attributes": {
                        "product": "MacBook Air",
                        "Brand": "Apple"
                    },
                    "platform": "iOS",
                    "app_version": "1.2.3",
                    "user_time": "1712567385726",
                    "current_time": "1712567385726"
                }
            ]
        }
            ]
}'

 

Array Support

If you want to pass an attribute in an array, the appropriate syntax for that is:

cURL
"Array_attributeName":["abc","123"],

The sample cURL for adding and removing elements in an array is:

cURL

curl --location 'https://s2s.moestaging.com/v1/transition/58FZ6XYHMPVH1JF4EPNWX6J9?app_id=58FZ6XYHMPVH1JF4EPNWX6J9' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic NThGWjZYWUhNUFZIMUpGNEVQTldYNko5OjdDUFp2TVRqV1VHM1dvZEtfM0BQK3V2Mg==' \
--data '{
    "type": "transition",
    "elements": [
        {
            "type": "customer",
            "customer_id": "OTBoS",
            "attributes": {
                "name": "wtmNx",
                "first_name": "bt016",
                "last_name": "JPCUi",
                "Array_attribute":["one","two"],
                "platforms": [
                    {
                        "platform": "iOS",
                        "active": "true"
                    }
                ]
            }
        },
        {
            "type": "device",
            "customer_id": "OTBoS",
            "device_id": "OTBoS",
            "attributes": {
                "brand": "Mi",
                "platform": "Windows",
                "push_id": "pushid1186"
            }
        },
        {
            "type": "event",
            "customer_id": "OTBoS",
            "actions": [
                {
                    "action": "mOhrP",
                    "attributes": {
                        "product": "Shoe"
                    },
                    "platform": "Windows",
                    "app_version": "581",
                    "user_time": "1712568861457",
                    "current_time": "1712568861457"
                }
            ]
        }
            ]
}'

    

 

Postman Collections

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

FAQs

  • Do the internal MoEngage validations of Track User API and Create Event API apply in Bulk API as well?
    Yes, Track User API validations apply to the type Customer payload. Create Event API validations apply to the type Event payload within the Bulk API request.

  • How do we reduce the 5xx errors because of too many requests per second or minute?
    Please attempt an exponential backoff of requests to ensure that there is no data loss due to 5xx errors.

  • How do I know if my user data has been ingested into MoEngage?
    Getting a 200 status code as a response from MoEngage only indicates that the users in your API payload have been accepted for processing. It does not ensure that the users sent to MoEngage have been successfully ingested.
    However, this happens very rarely and you can search for the newly ingested users in:
    Segment > Create Segment > Search for users using their IDs

Previous

Next

Was this article helpful?
2 out of 2 found this helpful

How can we improve this article?