Developer Docs

MoEngage Docs

discard

Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Data APIs

Data APIs allow you to send data from an unsupported platform, or if you need to track information that comes from outside your mobile app/website.

Suggest Edits

List of APIs

Required Parameters

app_id: Get the APP ID from the MoEngage dashboard under following path: (Settings > App Settings > Account Settings > APP ID).

Required Headers

Authentication

Data APIs use Basic authentication to control access to your data.

Basic authentication sends a Base64-encoded string that contains a username and password for your API requests. username and password are available under following path: (Settings > APIs > DATA API Settings) as shown below.

For first time, hit the Generate Key and then save on Data APIs settings page.
User name - DATA API ID
Password - DATA API KEY

Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. This is passed in the authorization header as follows
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

To send a request using a client (as Postman), Authentication can be done in following way:

Content-Type Header

To send data to Data APIs, Content-Type header must be set to 'application/json' as follows
{"Content-Type": "application/json"}

Request body

There is a max limit of 100kb per request.

Response

Response will be a json object, on a sucessful call you will receive response as

{"status":"success"}

on failure, response will be

{
  "status":"fail", 
  "error":{ 
    "type": "TypeError", 
    "attribute": "customer_id",
    "message":"expected string"
  }
}

Add/Modify User Information

API to use - User API
This API allows you to create a new user profile (or) update profile data of existing user. It includes customer_id (Unique Identifier of User) and other User Attributes(ex: name, age etc.. ). customer_id will be used to Map Actions and Devices to User.

NOTE: customer_id is essentially the Unique Identifier which is set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID

customer_id in customer payload is mandatory to identify a user profile.
platforms in customer attributes is mandatory to track platform level analytics.

Signature for a user API request looks like:

POST https://api.moengage.com/v1/customer?app_id=<APP ID>

To set name as John for a user with unique id john@example.com and platform android, pass the following payload

{
"type" : "customer",
"customer_id": "john@example.com",
"attributes": {
    "name":"John",
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

User attributes list is mentioned below:

  • name (string) - name of the user
  • first_name (string) - first name of the user
  • last_name (string) - last name of the user
  • email (string) - email of the user
  • age (numeric) - age of the user
  • gender (string) - "male" or "female" - case sensitive
  • mobile (string) - phone number of the user
  • geo (array of lat,lng in double) - location of the user for eg. [23.3,37.3]
  • source (string) - acquisition source of the user
  • created_time (numeric - epoch time in seconds) - user created time
  • last_seen (numeric - epoch time in seconds) - user last seen time
  • transactions (numeric) - no.of transactions done by the user
  • revenue (numeric) - LTV of the user
  • platforms (array) - platforms on which the user has interacted with the system. for eg.[{"platform":"ANDROID", "active":"true"},{"platform":"WINDOWS", "active":"true"},{"platform":"IOS", "active":"true"}]

To pass other attributes which are not part of the list, use the key value pairs that you intend to use. for ex. to set the points attribute for the user to 20 

{
"type" : "customer",
"customer_id": "john@example.com",
"attributes": {
    "points":20,
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

Mandatory fields: customer_id and platforms.

Add/Modify Device Information

API to use - Device API
This API allows you to create a new device profile (or) update profile data of existing device. It includes customer_id (Identifier of User), device_id (Identifier of Device) and other Device Attributes(ex: model, brand, os version etc.. ).

NOTE: customer_id is essentially the Unique Identifier which is set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID

customer_id in device payload is mandatory to map device to user.
platform in device attributes is mandatory to run platform level campaigns.
device_id in device payload is optional and default value is customer_id value. It will be used to update specific device in future.

Signature for a device API request looks like:

POST https://api.moengage.com/v1/device?app_id=<APP ID>
{
  "type": "device",
  "customer_id": "john@example.com",
  "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
  "attributes": {
    "model": "iPhone",
    "platform" : "iOS",
    "push_preference" : "true",
    "push_id" : "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I",
    "app_version" : "10.1",
    "os_version" : "2.5.4",
    "active" : "true",
    "created_time" : 143383676
  }
}

We defined reserved keywords for some of Device Attributes.

"model"  (string):  Model of Device
"platform" (string): os (ex: iOS)
"push_preference"  (string): is Push Enabled for Device ("true" or "false") 
"push_id" (string): Push Id or Push Token of Device. 
"app_version" : App Version
"os_version" : Os Version
"active" :   Installed status of device ("true" or "false")     
"created_time" : Created Time of Device (Epoch time in seconds)

To pass other attributes which aren't part of the list, use the key value pairs that you intend to use. for ex. to set the brand attribute for the device to Apple 

{
  "type": "device",
  "customer_id": "john@example.com",
  "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
  "attributes": {
    "brand": "Apple",
    "platform": "iOS",
    "push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
  }
}

Mandatory fields: customer_id, platform and push_id.

User Events Information

API to use - Event API
This API allows you to track actions of a user.

customer_id in event payload is mandatory to map event to user.
platform in event payload is mandatory to run platform level campaigns.
device_id in event payload is optional and default value is customer_id value. It will be used to map event to specific device.

Signature for event API request looks like:

POST https://api.moengage.com/v1/event?app_id=<APP ID>
{
    "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",
              "user_time" : 1433836769,
              "current_time" : 1433836769
          },
          {
              "action": "Purchase",
              "attributes": {
                "product"  : "MacBook Air",
                "Brand"  : "Apple"
              },
              "platform" : "web",
              "app_version" : "1.2.3",
              "user_time" : 1433837969,
              "current_time" : 1433837969
          }
     ]
}

We defined reserved keywords for some of Device Attributes.

"actions" (array) : Array of Actions or events
"action"  (string): Name of Action or Event
"attributes" (json object) - Event Attributes
"platform" (string) - os 
"app_version" (string or numeric) - App Version
"user_time" (Epoch Time in seconds) - User Time
"current_time" (Epoch Time in seconds) - GMT time of User Time

Mandatory fields: customer_id, action and platform.

Bulk Import

API to use - Transition API
This API allows you to import “user , device and event requests” in a single batch.

Signature for transition API request looks like:

POST https://api.moengage.com/v1/transition?app_id=<APP ID>
{
    "type" : "transition",
    "elements":[
        {
            "type" : "customer",
            "customer_id": "john@example.com",
            "attributes": {
                "name":"John",
                "platforms" : [{"platform":"ANDROID", "active":"true"}]
            }
        },
        {
            "type": "device",
            "customer_id": "john@example.com",
            "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
            "attributes": {
                "brand": "Apple",
                "platform": "iOS",
                "push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
            }
        },
        {
            "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",
                    "user_time" : 1433836769,
                    "current_time" : 1433836769
                },
                {
                    "action": "Purchase",
                    "attributes": {
                        "product"  : "MacBook Air",
                        "Brand"  : "Apple"
                    },
                    "platform" : "iOS",
                    "app_version" : "1.2.3",
                    "user_time" : 1433837969,
                    "current_time" : 1433837969
                }
            ]
        }            	
   	]
}

Change User Id

API to use - Customer Substitute API
This API is used to Update Unique Id of User (customer_id).

Signature for user substitute API request looks like:

POST https://api.moengage.com/v1/customer/substitute?app_id=<APP ID>
{
	"type": "customer_substitute",
	"old_customer_id": "john@example.com",
	"customer_id": "john123@example.com"
}
old_customer_id (string) : Old unique identifier for the User.
customer_id (string) : New unique identifier for the User.

Change Device Id

API to use - Device Substitute API
This API is used to Update Unique Id of Device (device_id).

Signature for device substitute API request looks like:

POST https://api.moengage.com/v1/device/substitute?app_id=<APP ID>
{
	"type": "device_substitute",
	"old_device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
	"device_id": "1234567890"
}
old_device_id (string) : Old unique identifier for the Device.
device_id (string) : New unique identifier for the Device.

GET User Attributes

API to retrieve user attributes based on the Unique ID that you have set for the user.

POST - https://api.moengage.com/v1/customer/export?app_id=<APP ID>

Basic Authentication is required

Request Body should contain the unique id details of the users for whom you need the profiles attributes.

{
    "customer_ids" : ["id1", "id2"]
}

A sample response is given below - 

{
  "customers": [
    {
      "id1": {
        "USER_ATTRIBUTE_ANDROID_ID": "android id",
        "USER_ATTRIBUTE_ADVERTISING_IDENTIFIER" : "Advertising Identifer iOS",
        "USER_ATTRIBUTE_USER_GENDER": "Male",
        "custom attribute that you track": "value of the custom attribute",
        "moe_dtzo": 330,
        "USER_ATTRIBUTE_LAST_KNOWN_STATE": "Ontario",
        "USER_ATTRIBUTE_NUM_SESSIONS": 2,
        "USER_ATTRIBUTE_LAST_KNOWN_COUNTRY": "Canada",
        "USER_ATTRIBUTE_USER_FIRST_NAME": "Deepakk",
        "USER_ATTRIBUTE_UNINSTALL_TIME": 1483420331,
        "USER_ATTRIBUTE_LAST_KNOWN_CITY": "Ottawa",
        "USER_ATTRIBUTE_USER_NAME": "John Cahill",
        "MOE_ISLAT": "0",
        "USER_ATTRIBUTE_USER_LAST_NAME": "John",
        "USER_ATTRIBUTE_USER_EMAIL": "joh@mail.com",
        "USER_ATTRIBUTE_ANDROID_GAID": "Advertising Identifier Android",
        "USER_ATTRIBUTE_UNIQUE_ID": "id1",
        "USER_ATTRIBUTE_USER_MOBILE": "12345678910",
        "USER_ATTRIBUTE_SIGNED_UP": 1483412907,
        "USER_ATTRIBUTE_LAST_SEEN": 1483414966,
        "USER_ATTRIBUTE_PLATFORMS": [
          {
            "active": true,
            "uninstall_time": 1483420331,
            "platform": "ANDROID"
          }
        ],
        "custom attribute like Personas":["Business Traveller", "Hotel Booker", "Music Listener"]
      }
    }
  ],
  "invalid_customer_ids": ["id2"]
}

Understanding Response -

'invalid_customer_ids' - List of unique ids, that don't match with any user in our system. User details contains all the custom attributes you track and also the default attributes which our system tracks. A list of default attributes and description is given below.

User Attribute
Description

USER_ATTRIBUTE_ANDROID_ID

android id for the user device.

USER_ATTRIBUTE_ADVERTISING_IDENTIFIER

iOS Advertising Identifier

USER_ATTRIBUTE_ANDROID_GAID

Android Advertising Identifier

MOE_ISLAT

Limited tracking enabled -> 0 - enabled. 1 - Disabled.

USER_ATTRIBUTE_LAST_KNOWN_COUNTRY

Last known country of the user.

USER_ATTRIBUTE_LAST_KNOWN_STATE

Last known state of the user.

USER_ATTRIBUTE_LAST_KNOWN_CITY

Last known city of the user.

moe_dtzo

user time zone offset in minutes.

USER_ATTRIBUTE_UNINSTALL_TIME

Uninstall time of the user (epoch time)

USER_ATTRIBUTE_NUM_SESSIONS

Number of sessions of the user.

USER_ATTRIBUTE_USER_NAME

Name of the user

USER_ATTRIBUTE_USER_FIRST_NAME

First name of the user.

USER_ATTRIBUTE_USER_LAST_NAME

Last name of the user

USER_ATTRIBUTE_USER_EMAIL

Email of the user

USER_ATTRIBUTE_USER_GENDER

Gender of the user - Male/Female

USER_ATTRIBUTE_USER_MOBILE

Mobile number of the user

USER_ATTRIBUTE_SIGNED_UP

First seen time of the user (epoch time)

USER_ATTRIBUTE_LAST_SEEN

Last seen time of the user (epoch time)

USER_ATTRIBUTE_PLATFORMS

list of platforms on which the user was active at least once in his lifetime.

Data APIs

Data APIs allow you to send data from an unsupported platform, or if you need to track information that comes from outside your mobile app/website.