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.
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.
servers:
- url: 'https://api-{dc}.moengage.com/v1'
description: MoEngage Core API Server
variables:
dc:
default: '01'
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](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. '
security:
- Authentication: []
paths:
# SECTION 1: USER
/customer/{app_id}:
post:
tags:
- User
summary: Track User
x-mint:
content: |
<Note>
- For more information about trackable user attributes, reserved keys, and general data information, refer to the [Data Overview](https://www.moengage.com/docs/api/data/data-overview).
- If you have [Portfolio](/user-guide/settings/account/portfolio/portfolio) enabled for your workspace, you must 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](/user-guide/data/key-concepts/portfolio-data-ingestion-and-management).
</Note>
#### Rate Limit
A single API request contains one or more user updates. Maintain a rate limit of 10,000 user updates per minute.
description: "This API adds or updates users and user properties in MoEngage. You can create a new user, create new user property, or update existing user properties of users."
parameters:
- name: app_id
in: path
required: true
description: |
This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.
schema:
type: string
example: VJ0GSMESHMQA3L7WV1EEK3UR
- 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/CreateUserRequest'
examples:
Standard Example:
summary: Sample cURL
value:
type: "customer"
customer_id: "john@example.com"
attributes:
name: "JohnDoe"
first_name: "John"
platforms:
- platform: "ANDROID"
active: "true"
User property as Date/Time:
summary: Example Payload
value:
type: "customer"
customer_id: "john@example.com"
update_existing_only: true
attributes:
points: 20
expiry_date: "2020-05-31T03:47:35Z"
super_user: true
user_persona: "browsers"
platforms:
- platform: "ANDROID"
active: "true"
User property as Array:
summary: Array Support
value:
type: "customer"
customer_id: "123"
attributes:
removeValueFromArrayField: {}
addValueToArrayField:
attribute1: ["abc", "def"]
attribute2: ["a"]
attribute3: ["123"]
platforms:
- platform: "iOS"
active: "true"
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
description: This field contains the status of the request and specifies whether the request was a failure.
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_customer_id:
summary: Customer ID is missing in the payload
value:
status: "fail"
error:
attribute: "customer_id"
message: "customer_id is not found in the payload"
type: "MissingAttributeError"
request_id: "ZbPXtKFL"
empty_customer_id:
summary: Customer ID is empty
value:
status: "fail"
error:
attribute: "customer_id"
message: "customer_id can not be empty Unicode String"
type: "MissingAttributeError"
request_id: "VgjtLxTu"
array_field_error:
summary: Array field error
value:
status: "fail"
error:
attribute: "addValueToArrayField"
message: "Cannot add and remove 'first_name' at the same time"
type: "ArrayFieldError"
request_id: "WPDAbugh"
'401':
description: This response is returned when the request does not have valid authentication credentials.
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 blocked. 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: "Susp123"
temp_suspended:
summary: Account is temporarily suspended
value:
status: "fail"
error:
message: "Your account is temporarily suspended due to payment issues."
type: "Account Temporarily Suspended"
request_id: "TempSusp123"
'413':
description: This response is returned when the payload size exceeds 128 KB.
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: "Unsupported Media Type"
type: "MediaTypeError"
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 limit exceeded"
type: "RateLimitError"
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: "Internal Server Error"
type: "ServerError"
request_id: "KovrwJiF"
/customers/export:
post:
tags:
- User
summary: Get User
x-mint:
content: |
#### Rate Limit
The rate limit is 20 users per payload and 1000 users per minute.
description: This API facilitates the retrieval of information of users by specifying the user IDs.
parameters:
- name: app_id
in: query
required: true
description: "This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**."
schema:
type: string
example: VJ0GSMESHMQA3L7WV1EEK3UR
- 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/GetUserRequest'
examples:
export_users:
summary: Export users by identifiers
value:
data:
identifiers:
- identifier_type: customer_id
identifier: "6416d1a318r98264512c0f89"
- identifier_type: id
identifier: "62e79fb15ada55x123g987bu"
user_fields_to_export:
- last_name
- customer_id
- name
responses:
'200':
description: This response is returned when the request is processed successfully.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: "This field contains the status of the request and specifies whether the request was successful. Supported values are : \"success\", \"failure\""
example: success
type:
type: string
description: "This field denotes the fetch type. Supported values are: \"export_users\"."
example: export_users
data:
type: object
description: |
This field contains the list of users who were not found in MoEngage and returns the data specified for the list of users who were found in MoEngage.
This is the structure:
```json
{
"users_not_found": [
{
"identifier_type": "customer_id",
"identifier": "<customer_id>"
}
],
"users": [
{
"user_attributes": {
"<list of user attributes>"
}
}
]
}
```
properties:
users_not_found:
type: array
description: "An array of JSON Objects that contains the list of users who were not found in MoEngage."
items:
$ref: '#/components/schemas/IdentifierObject'
users:
type: array
description: "Contains the user_attributes specified in the request for each user in specified in the request."
items:
type: object
properties:
user_attributes:
type: object
additionalProperties: true
example:
last_name: Doe
customer_id: john_doe
id: 62e79fb15ada55x123g987bu
examples:
success_response:
summary: Success Response
value:
status: "success"
type: "export_users"
data:
users_not_found:
- identifier_type: "customer_id"
identifier: "john_doe"
users:
- user_attributes:
last_name: "Doe"
customer_id: "john_doe"
name: "John"
custom_user_attr: 12345
id: "62e79fb15ada55x123g987bu"
'400':
description: "This response is returned when the required parameters APP KEY, user_id, and so on are missing from the request or when the provided params are invalid."
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: This field contains the status of the request and specifies whether the request was a failure.
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 (\"MissingAttributeError, Malformed JSON, LimitBreached\")."
request_id:
type: string
description: "A unique identifier for the request, useful for debugging."
attribute:
type: string
description: "The attribute in the payload that caused the error."
examples:
missing_identifiers:
summary: Identifiers are missing in the request
value:
status: "fail"
error:
attribute: "identifiers"
message: "identifiers is not found in the payload"
type: "MissingAttributeError"
request_id: "UkBwaUmU"
data_missing:
summary: Data is missing in the request
value:
status: "fail"
error:
attribute: "data"
message: "data is not found in the payload"
type: "MissingAttributeError"
request_id: "DataMiss2"
incorrect_json:
summary: JSON is incorrect in the request
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: "NphDCzWk"
limit_exceeded:
summary: Users exceeds the allowed limit in the request
value:
status: "fail"
error:
attribute: "users"
message: "max limit allowed is 20"
type: "LimitBreached"
request_id: "LimitX4"
'401':
description: Unauthorized.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: This field contains the status of the request and specifies whether the request was a failure.
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
description: This field contains the status of the request and specifies whether the request was a failure.
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: Sample response for when your account is blocked
value:
status: "fail"
error:
message: "Your account is suspended. Please contact MoEngage team."
type: "BlockedClient"
request_id: "ofHUEaEQ"
account_suspended:
summary: Sample response for when your account is suspended
value:
status: "fail"
error:
message: "Your account is suspended. Please contact MoEngage team."
type: "Account Suspended"
request_id: "gqJvCNYu"
temp_suspended:
summary: Sample response for when your 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 128 KB.
content:
application/json:
schema:
type: object
properties:
status:
type: string
description: This field contains the status of the request and specifies whether the request was a failure.
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
description: This field contains the status of the request and specifies whether the request was a failure.
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: "Unsupported Media Type"
type: "MediaTypeError"
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
description: This field contain
# --- truncated at 32 KB (212 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/moengage/refs/heads/main/openapi/moengage-data-openapi.yml