Create Event

The 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/{{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

  • 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.
  • If you have Portfolio enabled for your workspace, you need to pass project_code in the API endpoint. This identifies which project a user or event belongs to. For more information, refer to Portfolio: Data Ingestion and Management.

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:

  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 Data tile to copy the API key.
  3. 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.
If you are unsure about the platform on which the event occurred, send the value as unknown or do not send any value. Incorrect platform value leads to inconsistencies in platform level campaigns like Push and In-App.

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

  • 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)
    • 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:
    • ISO 8601 (for example - 2020-05-31T16:33:35Z)
    • Epoch time in seconds (for example - 1590404615)


User_timezone_offset

  • This field is crucial for establishing the User_time or Current_time.
  • This field should contain a numerical value between -54000 and 54000, representing the local timezone’s offset from UTC in seconds.
  • If the field is absent, 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 not present, 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 the request was received by MoEngage 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-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:

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

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

cURL

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:

  • For RokuTV, moe_os_type should be ROKU.
  • For LGTV, moe_os_type should be WebOS.
  • For AndroidTV,  moe_os_type should be AndroidTV.
  • For AppleTV, moe_os_type should be tvOS.
  • For SamsungTV, moe_os_type should be Tizen.
  • For FireTV, moe_os_type should be FireOS.
  • For VizioTV, moe_os_type should be VizioTV.
  • For Xbox, moe_os_type should be Xbox.

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

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.

 

 

Previous

Next

Was this article helpful?
15 out of 35 found this helpful

How can we improve this article?