> ## Documentation Index
> Fetch the complete documentation index at: https://moengage-sdk-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Create Event
> This API allows you to track the actions of a user.
* You cannot 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.
* 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.
* 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.
* 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.
### Example Payload
The example payload 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.To view the sample payload, select **example\_payload** from the drop-down.
### Array Support
If you want to pass an attribute in an array, the appropriate syntax for that is:
```json
"Array_attributeName":["abc","123"]
```
To view the sample cURL for adding and removing elements in an array, select **array\_support** from the drop-down.
### User Identity Resolution
If the [User Identity Resolution](https://help.moengage.com/hc/en-us/articles/24050999467284-Unified-Identity-Identity-Resolution) feature is enabled in your workspace, identifiers set up in the workspace must be mentioned within the user\_identifiers parameter. To view this sample payload where moe\_mobile is one of the identifiers, select **user\_identity\_resolution** from the drop-down.
## OpenAPI
````yaml /api/data/data.yaml post /event/{Workspace_ID}
openapi: 3.0.3
info:
title: MoEngage Data APIs
version: '1.0'
description: >-
This is a comprehensive OpenAPI specification for MoEngage's Data APIs,
including User, Event, and Device management.
It's designed to power an interactive API playground on your new
documentation site.
servers:
- url: https://api-0{dc}.moengage.com/v1
description: MoEngage Core API Server
variables:
dc:
default: '1'
description: >-
The ‘dc’ 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 and replace the value of ‘dc’ in the URL by referring
to the DC and API endpoint mapping
[here](https://help.moengage.com/hc/en-us/articles/360057030512-Data-Centers-in-MoEngage).
Your MoEngage Data Center (DC) can be 1, 2, 3, 4,5, 6.
enum:
- '1'
- '2'
- '3'
- '4'
- '5'
- '6'
security:
- Authentication: []
tags:
- name: User
description: Operations for creating, updating, retrieving, and managing user profiles.
- name: Event
description: Operations for tracking user events.
- name: Device
description: Operations for managing user devices.
- name: Tracking
description: Endpoints for tracking attribution and installs.
- name: Utilities
description: Utility endpoints for testing connections.
- name: File Imports
description: Operations for managing asynchronous file imports.
- name: Bulk
description: Operations for importing users and events in bulk.
- name: Webhooks
description: Incoming webhook specifications from MoEngage.
paths:
/event/{Workspace_ID}:
post:
tags:
- Event
summary: Create Event
description: This API allows you to track the actions of a user.
parameters:
- name: Workspace_ID
in: path
required: true
description: >-
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.
schema:
type: string
example: OAPQQ2AMD01MJZYZX1YPG
- name: X-Forwarded-For
in: header
required: false
description: >-
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.
schema:
type: string
example: 203.0.113.195
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEventRequest'
examples:
sample_cURL:
summary: Sample cURL
value:
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'
example_payload:
summary: Example Payload
value:
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
array_support:
summary: Array Support
value:
type: event
customer_id: John
actions:
- action: product_selected
attributes:
product: Shirt
color: Green
arraySupport:
- abc
- xyz
Brand: Adidas
platform: TV
moe_os_type: Xbox
app_version: 1.2.3
user_time: '1710740192'
current_time: '1710740192'
user_identity_resolution:
summary: User Identity Resolution
value:
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'
responses:
'200':
description: >-
This response is returned when the request is processed
successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/GenericSuccess'
examples:
success_response:
summary: Success Response
value:
status: success
message: Your request has been accepted and will be processed soon.
'400':
description: >-
This response is returned when the required parameters are missing
from the request, attributes are not found, and incorrect values are
passed.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
attribute:
type: string
description: The attribute in the payload that caused the error.
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error
("MissingAttributeError").
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
missing_actions:
summary: The actions are sent as an empty list
value:
status: fail
error:
attribute: actions
message: actions can not be empty Array
type: MissingAttributeError
request_id: izsZuQNw
missing_customer_id:
summary: Customer_id or user_alias is missing
value:
status: fail
error:
attribute: customer_id
message: customer_id is not found in the payload
type: MissingAttributeError
request_id: TtnwRNrU
incorrect_json:
summary: The elements in actions are not in json format
value:
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
missing_actionkey:
summary: >-
Action key is not present, or if it is not in string or
unicode string format
value:
status: fail
error:
attribute: action
message: action is not found in the payload
type: MissingAttributeError
request_id: TgzuJhcj
incorrect_action:
summary: Action key is not sent as a string
value:
status: fail
error:
attribute: action
message: >-
Could not decode the request body. The JSON was
incorrect or not encoded as UTF-8.
type: Malformed JSON
request_id: TgzuJhcj
'401':
description: This response is returned when the authentication error occurs.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error (e.g.,
Authentication required).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
auth_error:
summary: Authorization errors
value:
status: fail
error:
message: >-
App Secret key mismatch. Please login to the dashboard
to verify key
type: Authentication required
request_id: PVUDFisO
missing_header:
summary: Missing authentication header
value:
status: fail
error:
message: Authentication Header Required
type: Authentication required
request_id: PisPjGQQ
'403':
description: >-
This response is returned when your MoEngage account is suspended or
blocked.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.(e.g., Your account is suspended. Please
contact MoEngage team.)
type:
type: string
description: >-
The type or category of the error (e.g.,
BlockedClient, Account Suspended, Account Temporarily
Suspended).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
account_blocked:
summary: Account is blocked
value:
status: fail
error:
message: Your account is suspended. Please contact MoEngage team.
type: BlockedClient
request_id: Block123
account_suspended:
summary: Account is suspended
value:
status: fail
error:
message: Your account is suspended. Please contact MoEngage team.
type: Account Suspended
request_id: gqJvCNYu3
temp_suspended:
summary: Account is temporarily suspended
value:
status: fail
error:
message: >-
Your account is temporarily suspended. Please contact
MoEngage team.
type: Account Temporarily Suspended
request_id: ssSJjoyD
'413':
description: >-
This response is returned when the payload size exceeds the size
limit.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error (e.g., Payload too
large).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
payload_exceeded:
summary: Payloads exceeding the size limit
value:
status: fail
error:
message: Payload size exceeds 128 KB
type: PayloadTooLarge
request_id: VFzDwhwt
'415':
description: This response is returned when the content type is not supported.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error (e.g., Unsupported
media type).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
unsupported_media_type:
summary: Unsupported media type
value:
status: fail
error:
message: Content type is not supported
type: Unsupported media type
request_id: SgBQfKJh
'429':
description: >-
This response is returned when the number of requests has exceeded
the rate limit.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error (e.g., Rate Limits
Exceeded).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
rate_limit:
summary: Rate limit breach
value:
status: fail
error:
message: >-
Rate limits for customers exceeded. Please Try After
Some Time
type: Rate Limits Exceeded
request_id: onqucLYL
'500':
description: >-
This response is returned when the system runs into an unexpected
error.
content:
application/json:
schema:
type: object
properties:
status:
type: string
example: fail
error:
type: object
properties:
message:
type: string
description: >-
A descriptive error message explaining why the request
failed.
type:
type: string
description: >-
The type or category of the error (e.g., Server
Error).
request_id:
type: string
description: >-
A unique identifier for the request, useful for
debugging.
examples:
unknown_error:
summary: Unknown errors
value:
status: fail
error:
message: >-
An unexpected error was encountered while processing
this request. Please contact MoEngage Team
type: ServerError
request_id: KovrwJiF
components:
schemas:
CreateEventRequest:
title: Event
type: object
required:
- type
- customer_id
- actions
properties:
type:
type: string
description: >-
This is used to identify the type of request. Allowed value is
event.This field is case-sensitive. Follow the case as in the
example when passing the value in the request.
enum:
- event
customer_id:
type: string
description: >-
Identifier to identify or create a user in MoEngage. Not mandatory
in Identity resolution enabled workspaces.
device_id:
type: string
description: >-
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.
user_identifiers:
type: object
description: >-
Required if Identity Resolution is enabled and customer_id is not
provided.
additionalProperties: true
example:
moe_mobile: '+919876543210'
actions:
type: array
items:
$ref: '#/components/schemas/EventAction'
GenericSuccess:
type: object
properties:
status:
type: string
description: >-
This field contains the status of the request and specifies whether
the request was successful.
example: success
message:
type: string
example: Your request has been accepted and will be processed soon.
EventAction:
type: object
required:
- action
properties:
action:
type: string
description: The name of the event to be tracked.
attributes:
type: object
additionalProperties: true
description: A dictionary containing event attributes to track with the event.
example:
price: 3999
departure_date: '2019-05-21T03:47:35Z'
premium_seat: true
platform:
type: string
enum:
- ANDROID
- iOS
- web
- unknown
description: >-
Used to identify the platform on which the event happened. Allowed
values are ANDROID, iOS, web, or unknown.
app_version:
type: string
description: App Version of the app on which the event originated.
user_time:
oneOf:
- type: number
- type: string
description: >
Local time at which the event happened. (Epoch seconds or ISO 8601
string). 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)
current_time:
oneOf:
- type: number
- type: string
description: >
UTC time at which the event happened. (Epoch seconds or ISO 8601
string). 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_timezone_offset:
type: number
description: >
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.
* 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.
securitySchemes:
Authentication:
type: http
scheme: basic
description: >
This authentication parameter, used for access control, must be passed
along with the request. 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.
Use these details to authenticate the API requests.
````