The Create Event API allows you to track the actions of a user.
API Endpoint
Method: POST
https://api-0X.moengage.com/v1/event/{{appId}}
The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage maintains different data centres for different clients. 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
|
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_WORKSPACEID_APIKEY=="}
The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:
- Navigate to Settings -> Account -> APIs.
- Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Data tile to copy the API key.
- Use these details to authenticate the API requests.
Request Parameters
| Key | Required | Data Type | Description |
|---|---|---|---|
|
app_id |
Yes |
String |
This is your MoEngage account's Workspace ID that has to be passed along with the request. You can find your MoEngage Workspace ID at Settings > Account > APIs > Workspace ID. |
Request Headers
| Key | Required | Sample Values | Description |
|---|---|---|---|
|
X-Forwarded-For |
Yes |
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 |
Yes |
{"Content-Type": "application/json"} |
Set the Content-Type header to application/json. |
|
Authorization |
Yes |
{"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
| info |
Note You can not use "moe_" as a prefix while naming events, event attributes, or user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication. |
Request Body Fields
| Key | Data Type | Required | Description |
|---|---|---|---|
| type | String | Yes | This is used to identify the type of request. Allowed Value: event Example: "type": "event" Note: This field is case-sensitive. Follow the case as in the example when passing the value in the request. |
| customer_id | String | Yes |
Identifier to identify or create a user in MoEngage. Not mandatory in Identity resolution enabled workspaces. |
| device_id | String | No | device_id in event payload is optional. The default value is the customer_id value. The value is used to map events to specific devices. |
| actions | List | Yes | List of events to be tracked for the user. |
| action | String | Yes | The name of the event to be tracked. |
| attributes | JSON Object | No | A dictionary containing event attributes to track with the event. |
| platform | String | No | Used to identify the platform on which the event happened. Allowed values are ANDROID, iOS, web, or unknown. |
| app_version | String | No | App Version of the app on which the event originated. |
| user_time | Numeric (Epoch time in seconds) or String (ISO 8601) | No | Local time at which the event happened. |
| current_time | Numeric (Epoch time in seconds) or String( ISO 8601) | No | UTC time at which the event happened. |
| user_timezone_offset | Numeric | No |
The difference in time between UTC and the local system time in a particular time zone. All time zones are defined by their offset from UTC. The offset is expressed as either UTC- or UTC+. user_timezone_offset should have a value in seconds which can be between -54000 to 54000. For example, for IST (UTC+0530), "user_timezone_offset" will be 19800. |
| warning |
Warning Ensure that the platform value sent is Android, iOS, or web. Platform value depends on which platform the event was generated. MoEngage does not accept any future dated events. |
| info |
Note This note helps you understand the differences between Current_time, User_time, and User_timezone_offset. Current_time
|
Example Payload
The following example provides tracking of numeric, boolean, and date type event attributes.
Use the payload described, where the price is numeric, departure_date is a date type attribute and premium_seat is a boolean attribute.
{
"type": "event",
"customer_id": "john@example.com",
"actions": [{
"action": "Flight Booked",
"attributes": {
"price": 3999,
"departure_date": "2019-05-21T03:47:35Z",
"premium_seat": true
},
"platform": "iOS",
"app_version": "1.2.3",
"current_time": 1433837969,
"user_timezone_offset": 19800
}
]
}
Response Codes
Success Response
{
"status": "success",
"message": "Your request has been accepted and will be processed soon."
}
Sample response if the actions are sent as an empty list:
{
"status": "fail",
"error": {
"attribute": "actions",
"message": "actions can not be empty Array",
"type": "MissingAttributeError",
"request_id": "izsZuQNw"
}
}
Sample response if the customer_id or user_alias is missing:
{
"status": "fail",
"error": {
"attribute": "customer_id",
"message": "customer_id is not found in the payload",
"type": "MissingAttributeError",
"request_id": "TtnwRNrU"
}
}
Sample response if the elements in actions are not in json format:
{
"status": "fail",
"error": {
"message": "Could not decode the request body. The JSON was incorrect or not encoded as UTF-8.",
"type": "Malformed JSON",
"request_id": "USkbHpIK"
}
}
Sample response if the action key is not present, or if it is not in string or unicode string format:
{
"status": "fail",
"error": {
"attribute": "action",
"message": "action is not found in the payload",
"type": "MissingAttributeError",
"request_id": "TgzuJhcj"
}
}
Sample response if the action key is not sent as a string:
{
"status": "fail",
"error": {
"message": "Could not decode the request body. The JSON was incorrect or not encoded as UTF-8.",
"type": "Malformed JSON",
"request_id": "USkbHpIK"
}
}
Sample response for authorization errors
{
"status": "fail",
"error": {
"message": "App Secret key mismatch. Please login to the dashboard to verify key",
"type": "Authentication required",
"request_id": "PVUDFisO"
}
}
Sample response for missing authentication header
{
"status": "fail",
"error": {
"message": "Authentication Header Required",
"type": "Authentication required",
"request_id": "PiSPjGQQ"
}
}
Sample response for when your account is blocked
{
"status": "fail",
"error": {
"message": "Your account is suspended. Please contact MoEngage team.",
"type": "BlockedClient",
"request_id": "ofHUEaEQ"
}
}
Sample response for when your account is suspended
{
"status": "fail",
"error": {
"message": "Your account is suspended. Please contact MoEngage team.",
"type": "Account Suspended",
"request_id": "gqJvCNYu"
}
}
Sample response for when your account is temporarily suspended
{
"status": "fail",
"error": {
"message": "Your account is temporarily suspended. Please contact MoEngage team.",
"type": "Account Temporarily Suspended",
"request_id": "ssSJjoyD"
}
}
Sample response for payloads exceeding the size limit
{
"status": "fail",
"error": {
"message": "Payload can not exceed 128KB",
"type": "Payload too large",
"request_id": "VFzDwhwt"
}
}
Sample response for unsupported media type
{
"status": "fail",
"error": {
"message": "Content type is not supported",
"type": "Unsupported media type",
"request_id": "SgBQfKJh"
}
}
Sample response for rate limit breach
{
"status": "fail",
"error": {
"message": "Rate limits for customers exceeded. Please Try After Some Time",
"type": "Rate Limits Exceeded",
"request_id": "onqucLYL"
}
}
Sample response for unknown errors
{
"status": "fail",
"error": {
"message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team",
"type": "Server Error",
"request_id": "KovrwJiF"
}
}
Sample cURL Request
curl --location --request POST 'https://api-0X.moengage.com/v1/event/{{appId}}?app_id={{appId}}' \
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data-raw '{
"type": "event",
"customer_id": "123",
"actions" : [
{
"action": "ProductAdded",
"attributes": {
"product" : "Accessories",
"color" : "Black",
"Brand" : "Adidas"
},
"platform" : "Android",
"app_version" : "1.2.3",
"user_time" : "1708939453396",
"current_time" : "1708939453396"
}
]
}'
Array Support
If you want to pass an attribute in an array, the appropriate syntax for that is:
"Array_attributeName":["abc","123"],
The sample cURL for adding and removing elements in an array is:
curl --location --globoff 'https://api-0X.moengage.com/v1/event/{{appId}}?app_id={{appId}}' \
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data '{
"type": "event",
"customer_id": "John",
"actions" : [
{
"action": "product_selected",
"attributes": {
"product": "Shirt",
"color": "Green",
"arraySupport":["abc","xyz"],
"Brand": "Adidas"
},
"platform": "Android",
"app_version" : "1.2.3",
"user_time": "1710740192",
"current_time": "1710740192"
}
]
}'
| info |
Information Following are the valid moe_os_type accepted in Moengage:
|
User Identity Resolution
If the User Identity Resolution feature is enabled in your workspace, identifiers set up in the workspace must be mentioned within the user_identifiers parameter, as shown in the following example where moe_mobile is one of the identifiers in the workspace:
is:
curl --location --request POST 'https://api-0X.moengage.com/v1/event/{{appId}}?app_id={{appId}}' \
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data-raw '{
"type": "event",
"user_identifiers":{
"moe_mobile":"{{Mobile_Number}}"
},
"actions" : [
{
"action": "product_selected",
"attributes": {
"product" : "Shirt",
"color" : "Green",
"moe_os_type":"Xbox",
"arraySupport":["abc","xyz"],
"Brand" : "Adidas"
},
"platform" : "TV",
"app_version" : "1.2.3",
"user_time" : "1710740192",
"current_time" : "1710740192"
}
]
}'
For more information, refer to User Identity Resolution.
Postman Collections
We have made it easy for you to test the APIs. Click here to view it in Postman.
FAQs
-
How to identify the events to a given user? What identifiers can I use?
Events in the payload need to be mapped to a given user who has executed the event. You must use the Customer ID to identify the events mapped to a customer. -
Can I send events for anonymous users?
No, anonymous users can be tracked using MoEngage SDKs. -
Can events be updated/modified?
Events in MoEngage are immutable, i.e. events can only be created, they cannot be updated or deleted.