Create Event

This Create Event API allows you to track the actions of a user.

API Endpoint

Method: POST

API Endpoint
https://api-0X.moengage.com/v1/event/<WORKSPACE_ID>

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

info

Information

The Workspace_ID for your MoEngage account is available on the MoEngage Dashboard. You can find the WORKSPACE_ID in Settings -> Account -> APIs -> Workspace 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"}

You can obtain the username and password details from the MoEngage Dashboard.

  1. Navigate to Settings > Account > APIs.
  2. 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 Campaign report/Business events/Custom templates/Catalog API tile to copy the API key.
    • Use these details to authenticate the API requests.

Request Headers

Key Required Sample Values Description
app_id Required String

This is your MoEngage account's Workspace ID that has to be passed along with the request.

X-Forwarded-For Optional 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 Required

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

Set the Content-Type header to application/json.

Authorization Required

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

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

info

Information

Do not use "moe_" as a prefix when naming events, event attributes, or user attributes. It is a system prefix and its use may result in periodic blacklisting without prior communication.

 

Request Body

Key Required Values Description
type Required String

This is used to identify the type of request. The allowed value is event. For example, type: event.

Note: This field is case-sensitive. When you pass this value in the request, use the same case shown in the example.

customer_id Required String

This is an identifier to identify or create a user in MoEngage. This is not mandatory in workspaces where Identity Resolution is enabled.

device_id Optional String

This device_id in the event payload is optional. The default value is the customer_id, which maps events to specific devices.

actions Required String

This is the list of events to be tracked for the user.

attributes Optional JSON Object

This is the list of event attributes to track for the event.

platform Optional String

This field identifies the platform where the event occurred. Allowed values are ANDROID, iOS, web, or unknown.

app_version Optional String

This is the app version where the event originated.

user_time Optional Numeric (Epoch time in seconds) or String (ISO 8601)

This is the local time when the event occurred.

current_time Optional Numeric (Epoch time in seconds) or String( ISO 8601)

This is the UTC time when the event occurred.

user_timezone_offset Optional Numeric

This field represents the difference in time between Coordinated Universal Time (UTC) and the local system time in a particular time zone. All time zones are defined by their offset from UTC, which is expressed as either UTC—or UTC+.

The user_timezone_offset should be a value in seconds, ranging from -54000 to 54000. For example, for Indian Standard Time (IST) (UTC+05:30), the user_timezone_offset value is 19800

 


warning

Warning

Send one of the following values for the platform: Android, iOS, or web. The platform value indicates the platform where the event originated. If the platform of origin is uncertain, send the value as unknown or do not send any value. Incorrect platform values can cause inconsistencies in platform-level campaigns, such as Push and In-App.
MoEngage does not accept future-dated events.

 

info

Information

Current_time

This field is necessary to specify the UTC time of the event.

Acceptable formats for current_time include: ISO 8601 (For example, 2020-05-31T16:33:35Z)and Epoch time in seconds (For example, 1590404615).

User_time

This field lets the system identify the local system time for when the event happened.

Acceptable formats for user_time are ISO 8601 (for example, 2020-05-31T16:33:35Z)and Epoch time in seconds (for example, 1590404615).

User_timezone_offset

This field is crucial for establishing the User_time or Current_time. This contains a numerical value between 54000 and 54000, representing the local timezone’s offset from UTC in seconds. MoEngage gets this information from the internal system in the sequence as follows:

  • The user profile’s timezone is taken into consideration.
  • If the user profile’s timezone is absent, the App/account’s timezone is considered.
  • In cases where neither is present, the UTC timezone is used.
  •  
  • Only include User_timezone_offset in your request if you have accurate timezone information for each user, as incorrect info could disrupt event timelines in the user profile.

Fields to be Provided

MoEngage generates Current_time and User_time if they are not provided in the request. Use the following information and provide Current_time, User_time, and User_timezone_offset accordingly:

  • If you don't provide any of Current_time, User_time, and User_timezone_offset, MoEngage automatically uses the UTC time when MoEngage received the request as the Current_time. MoEngage uses internal data to calculate the User_timezone_offset to generate the User_time.
  • If you provide only the Current_time, MoEngage uses internal data to calculate the User_timezone_offset to generate the User_time.
  • If you provide only the User_time, MoEngage uses internal data to calculate the User_timezone_offset to generate the Current_time.
  • If you send the Current_time and User_time, MoEngage uses them as is.
  • If you provide the Current_time and User_timezone_offset, MoEngage generates the User_time.
  • If you provide User_time and User_timezone_offset, MoEngage generates the 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.

JSON
{
    "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

200 400 401 403 413 415 429 500
Success Response
{ "status": "success", "message": "Your request has been accepted and will be processed soon." }

Sample cURL Request

cURL

curl --location --request POST 'https://api-01.moengage.com/v1/event/OAPQQ2AMD01MJZYZX1YPG?app_id=OAPQQ2AMD01MJZYZX1YPG' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic T0FQUVEyQU1EMDFNSMlRZWlgxWVBHOmxVcURvd2JqeGpleGdzR1ZVdlNA==' \
--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

To pass an attribute in an array, use the following:

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

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

cURL


curl --location --request POST 'https://api-01.moengage.com/v1/event?app_id=VJ0GABESHMQA3L7WK3UR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VkoNNRVNITVFBM0w3V1YxRUVLM1VSOkZJd0N5dGZ0QWpZcl9tcVlldkVPVkFtbw==' \
--data-raw '{
    "type": "event",
    "customer_id": "John",
    "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"
          }
     ]
}'


    

User Identity Resolution

If the User Identity Resolution feature is enabled in your workspace, include the workspace's configured identifiers within the user_identifiers parameter, where moe_mobile is one of the identifiers, as shown in the following:

cURL


curl --location --request POST 'https://api-01.moengage.com/v1/event?app_id=VJ0GABESHMQA3L7WK3UR' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic VkoNNRVNITVFBM0w3V1YxRUVLM1VSOkZJd0N5dGZ0QWpZcl9tcVlldkVPVkFtbw==' \
--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. They can only be created; they cannot be updated or deleted.

 

 

Previous

Next

Was this article helpful?
12 out of 29 found this helpful

How can we improve this article?