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: - Basic Auth: [] - OAuth 2.0: [] paths: # SECTION 1: USER /customer/{app_id}: post: tags: - User summary: Track User x-mint: content: | - 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). - [Unsetting Attributes](/user-guide/data/user-data/unset-user-attributes) is an Early Access feature. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team. #### 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" Unsetting Attributes: summary: Clear Attributes value: type: "customer" customer_id: "user123" unset_attributes: - type: "equals" attr: "first_name" case_sensitive: false - type: "prefix" attr: "temp_" 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" '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: | - Access to Get User is gated because the endpoint can return PII. To enable it for your workspace, contact your CSM or raise a ticket with MoEngage Support. The request creates an audit trail of who asked for access. Workspaces already using the API before gating was introduced were enabled automatically. - Get User is a **single-lookup** API, you pass one or more identifiers and get back the matching user profile(s), up to the payload limit below. It does not support a "retrieve all users" mode; there's no parameter on this endpoint to export your entire user base. If you need to export all users, use a separate bulk/file export flow instead. - You can optionally IP-whitelist the callers permitted to invoke this endpoint. #### 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": "" } ], "users": [ { "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" '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 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., 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 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., 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" /customer/merge: post: tags: - User summary: Merge Users x-mint: content: | #### Types of user merging in MoEngage * Default or normal merge: * MoEngage merges users with the same ID. * Happens automatically, and no action is required from your side. * Manual merge: * MoEngage merges users having different IDs. * Does not happen automatically; you must call the Merge User API with the list of users to be merged along with their IDs. * User Merging is a complex functionality and, if misused, can lead to data integrity issues. If the data passed to the API is incorrect, resulting in a merge of two unintended users, MoEngage will not be able to recover/rectify the data. The retained user would have erroneous data, and segmentation queries would not provide the right results. * MoEngage does not support transitive/canonical merging. For example, if user A is merged to B (A ->B) and then user B is merged to C (B ->C), in this scenario, events of user A are not moved to user C. * The Merge User API is not functional in workspaces where the [Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) feature is enabled. * If you are updating the [Unique Identifier](/developer-guide/unity-sdk/data-tracking/tracking-user-attributes) for a user, use the Merge User API at least 2 hours after you have updated the Unique Identifier. * Ensure that the data passed to the API is accurate. We recommend you test the merging starting with a small batch of users, such as 1, 5, 10, 20, 50, etc. Verify the merged data and users before proceeding with a bulk update. * A maximum of 50 users can be merged in a single call. * Payload size should not exceed 128 KB. #### Rate limit The rate limit is 1000 user updates per minute. description: This API merges two users in MoEngage based on their ID, which is a client-defined identifier for a user. You can use this API when multiple profiles have been created for a single user. For example, you can merge a user registered once with a mobile number and once with an email ID. You can also merge duplicate users created due to integration or tech issues. 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MergeUserRequest' 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 operation: type: string description: This field contains “created” when there is no error in the payload, and the user merge is successful. example: created examples: success_response: summary: Successful request value: status: "success" operation: "created" '400': description: "This response is returned when the required parameters are missing from the request or when the provided parameters 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 (e.g., Malformed JSON)." request_id: type: string description: "A unique identifier for the request, useful for debugging." examples: malformed_json: summary: Malformed JSON 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: "pIvbWnGT" app_blacklisted: summary: App blacklisted by MoEngage value: status: "fail" error: message: "Your account is blacklisted, Please contact MoEngage." type: "Blacklisted" request_id: "pIvbWnGT" invalid_workspaceid: summary: Invalid Workspace ID in request parameter value: status: "fail" error: message: "given app_id is invalid/blocked" type: "InvalidParams" request_id: "pIvbWnGT" missing_workspaceid: summary: Workspace ID not present in the Request Parameter value: status: "fail" error: message: "app_id is required in path/query params." type: "ParamsRequired" request_id: "pIvbWnGT" invalid_payload: summary: Workspace ID not present in the Request Parameter value: status: "fail" error: message: "A valid JSON document is required." type: "Body type is not JSON" request_id: "pIvbWnGT" empty_request: summary: Empty request body value: status: "fail" error: message: "A valid JSON document is required." type: "Body type is not JSON" request_id: "pIvbWnGT" invalid_datatype: summary: Invalid datatype value: status: "fail" error: attribute: "merged_user" message: "merged_user is expected to be String or Unicode String." type: "MissingAttributeError" request_id: "dBSEscwl" suspended_account: summary: Suspended MoEngage account used in the request value: status: "fail" error: message: "Account Suspended." type: "Account Suspended" request_id: "pIvbWnGT" '401': description: This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header. 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: incorrect_header: summary: Incorrect values for the APP KEY/ HTTP Auth Header value: status: "fail" error: message: "MOE_APPKEY doesn't match the Username (APP_KEY) used in Basic Auth authorization." type: "Authentication required" request_id: "pIvbWnGT" missing_header: summary: Missing APP KEY in HTTP Auth Header value: status: "fail" error: message: "MOE-APPKEY is missing in Header" type: "Authentication required" request_id: "pIvbWnGT" missing_appsecret: summary: Missing APP SECRET in HTTP Auth Header value: status: "fail" error: message: "MOE-APPKEY is missing in Header" type: "Authentication required" request_id: "pIvbWnGT" missing_username: summary: Username is not provided in the Auth header value: status: "fail" error: message: "Username (APP_KEY) is missing in the Basic Auth authorization." type: "Authentication required" request_id: "pIvbWnGT" missing_password: summary: Password is not provided in the Auth header value: status: "fail" error: message: "Password (APP_SECRET) is missing in the Basic Auth authorization." type: "Authentication required" request_id: "pIvbWnGT" invalid_auth: summary: Other authorization type is used instead of Basic Auth value: status: "fail" error: message: "Invalid authorization used. MoEngage only supports 'Basic Auth' authorization." type: "Authentication required" request_id: "pIvbWnGT" missing_authdetails: summary: Authorization details are missing in the header value: status: "fail" error: message: "Authorization details are missing" type: "Authentication required" request_id: "pIvbWnGT" invalid_appkey: summary: Invalid APP Secret key in Authorization Header value: status: "fail" error: message: "App Secret key mismatch. Please login to the dashboard to verify key" type: "Authentication required" request_id: "JooAzchF" incorrect_appkey: summary: Incorrect APP KEY value: status: "fail" error: message: "Password (APP_KEY) doesn't match the one available on the dashboard. Kindly ensure the same APP_KEY available on the dashboard is used." type: "Authentication required" request_id: "pIvbWnGT" '403': description: This response is returned when the user account that is being merged has been suspended temporarily. 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., Account Temporarily Suspended)." request_id: type: string description: "A unique identifier for the request, useful for debugging." examples: account_suspension: summary: Temporary account suspension value: status: "fail" error: message: "Account Temporarily Suspended." type: "Account Temporarily Suspended." request_id: "pIvbWnGT" '409': description: This response is returned when the authorization fails due to the APP SECRET key not being set on the Dashboard. 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: authorization_errors: summary: Authorization errors due to APP SECRET not being set in the Dashboard value: status: "fail" error: message: "App Secret key is not set. Please login to the dashboard to set a key." type: "Authentication required." request_id: "pIvbWnGT" appkey_mismatch: summary: Mismatch in the app id sent in the request parameter and the authorization header value: status: "fail" error: message: "App key mismatch in params and authentication." type: "Authentication required." request_id: "WNqwxfwM" '413': description: TThis response is returned when the payload size has exceeded the limit set. 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: Request Payload Size Exceeded value: status: "fail" error: message: "The payload can not exceed 128KB" type: "PayloadTooLarge" request_id: "VFzDwhwt" '429': description: This response is returned when the number of requests per minute has exceeded the rate limit. 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., 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 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., 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" /customer/delete: post: tags: - User summary: Delete Users x-mint: content: | #### Rate Limit The rate limit is 1 user per payload per request. You can run 5000 requests per minute. description: | This API deletes users in MoEngage. You cannot retrieve users once deleted. Users deleted (hard delete) using this API will be deleted after a default buffer of 24 hours. During this buffer period, the user will still be active in MoEngage and will be visible in Segments, Analytics, and Campaigns. You can update users in the buffer period. After the buffer elapses, the user is hard-deleted from MoEngage. If you create a user with the same unique identifiers as the deleted one in MoEngage (through APIs or imports), they will be created again in MoEngage. 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: properties: identity_type: type: string enum: [customer_id, moengage_id] description: This field specifies the identifier type. Identifier types can either be customer_id (ID field in the User Profile) or moengage_id (the MoEngageID of the user in the User Profile). Allowed values are "moengage_id", "customer_id". example: customer_id identity_value: type: string description: This field specifies the unique identifier that identifies the user. example: 6416d1a318r98264512c0f89 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, fail" example: success message: type: string description: This field contains information about whether the response is being processed, the user is deleted, and so on. example: Your request has been accepted and will be processed soon examples: success_response: summary: Successful request value: status: "success" message: "Your request has been accepted and will be processed soon." '400': description: "This response is returned when the required parameters APP KEY, user_id, etc 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 successful. Supported values are success, fail example: fail error: type: object properties: message: type: string description: "This field contains the error message and describes the reason for the error." type: type: string description: "The type or category of the error (e.g., Authentication Required, Invalid Params)." request_id: type: string description: "A unique identifier for the request, useful for debugging." examples: bad_request: summary: Bad Requests value: status: "fail" error: message: "User doesn't exists with customer id b3XSJ7iXvqlCcrYGd5SB5m2m93eG9-9e9HPXd9GtufHvHueWm-mnuiAxUk7DGI1MKg==" type: "Not Found" request_id: "bYvNTyWb" '401': description: This response is returned when the authorization fails due to incorrect values for the APP KEY/ HTTP Auth Header. 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, fail example: fail error: type: object properties: message: type: string description: "This field contains the error message and describes the reason for the error" type: type: string description: 'The type or category of the error (e.g., Authentication Required, Invalid Params).' request_id: type: string description: "A unique identifier for the request, useful for debugging." examples: authorization_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: "pIvbWnGT" '403': description: This response is returned when your MoEngage account has been blocked or suspended. 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, fail example: fail error: type: object properties: message: type: string description: This field contains the error message and describes the reason for the error type: type: string description: "The type or category of the error (e.g., Authentication Required, Invalid Params)." request_id: type: string description: "A unique identifier for the request, useful for debugging." examples: appid_invalid: summary: Blocked/Suspended Accounts value: status: "fail" error: message: "given app_id is invalid/blocked" type: "InvalidParams" request_id: "pIvbWnGT" '429': description: This response is returned when the number of requests per minute has exceeded the rate limit. content: application/json: schema: type: object properties: title: type: string description: This field is present in the response in the case of 429 and 5xx errors and contains the type of error. description: type: string description: This field is present in the response in the case of 429 and 5xx errors and contains the error description. examples: rate_limit: summary: Rate limit breach value: status: "fail" title: "Rate limit exceeded" description: "Exceeded rate limit for this url" '500': description: This response is returned when the system runs into an unexpected error. content: application/json: schema: type: object properties: title: type: string description: This field is present in the response in the case of 429 and 5xx errors and contains the type of error. description: type: string description: This field is present in the response in the case of 429 and 5xx errors and contains the error description. examples: unknown_error: summary: Unknown errors value: status: "fail" title: "Internal Error" description: "Please contact the MoEngage team." # SECTION 2: EVENT /event/{Workspace_ID}: post: tags: - Event summary: Track Event x-mint: content: | * If you have [Portfolio](/user-guide/settings/account/portfolio/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](/user-guide/data/key-concepts/portfolio-data-ingestion-and-management). * MoEngage does not accept any future dated events. #### Rate Limit A single API request contains one or more events. Maintain a rate limit of 30,000 events per minute. description: This API tracks the actions of a user. parameters: - name: Workspace_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: 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: description: | **Note**: 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. required: true content: application/json: schema: $ref: '#/components/schemas/CreateEventRequest' examples: Standard Example: 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: "1708939453" current_time: "1708939453" Event property as Date/Time: 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 Event property as Array: 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" Using User Identifiers: 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: 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." attribute: type: string description: "The attribute in the payload that caused the error." 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" '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" # SECTION 3: DEVICE /device/{app_id}: post: tags: - Device summary: Track Device x-mint: content: | #### Rate Limit A single API request contains one or more device updates. Maintain a rate limit of 10,000 device updates per minute. description: This API adds or updates devices and device properties in MoEngage. You can create a new device for an existing user, create new device properties for an existing user, or update the device properties of the existing user. 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/CreateDeviceRequest' 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_customerid: summary: Customer_id is missing value: status: "fail" error: attribute: "customer_id" message: "'customer_id' is not found in the payload" type: "MissingAttributeError" request_id: "izsZuQNw" missing_attributes: summary: Attributes is missing value: status: "fail" error: attribute: "attributes" message: "'attributes' is not found in the payload" type: "MissingAttributeError" request_id: "MwNnVDsC" invalid_platform: summary: Invalid platform value: status: "fail" error: attribute: "platform" message: "'platform' is not a valid platform." type: "ValueError" request_id: "NDuFDLwS" missing_pushid: summary: Push_id is missing value: status: "fail" error: attribute: "push_id" message: "'push_id' is not found in payload" type: "MissingAttributeError" request_id: "dsLXpKgJ" missing_platform: summary: Platform is not found in payload value: status: "fail" error: attribute: "platform" message: "'platform' is not found in payload" type: "MissingAttributeError" request_id: "gyLYpBFV" '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 suspended. Please contact MoEngage team." type: "BlockedClient" request_id: "ofHUEaEQ" 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 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" '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" /devices/manage: post: tags: - Device summary: Device Opt-out description: This API blocks or unblocks specific devices from receiving push notifications triggered from MoEngage. To prevent push notifications from reaching a specific user or all devices associated with a user, call the API to block them. This is useful for reasons such as device theft or fraudulent activity. For example, if a device is stolen, you can use this API to block it in MoEngage, ensuring that any scheduled push notifications with sensitive content do not get delivered. You can also use the API to unblock a device if it is recovered. x-mint: content: | #### Rate Limit The rate limit is 1000 API requests per minute. 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeviceOptOutRequest' 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: 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." attribute: type: string description: "This field denotes the attribute missing in the payload." examples: missing_useridentifiervalue: summary: User_identifier_value is missing in the payload value: status: "fail" error: attribute: "user_identifier_value" message: "user_identifier_value is not found in the payload" type: "MissingAttributeError" request_id: "YRJTbvRM" missing_useridentifiertype: summary: User_identifier_type is missing in the payload value: status: "fail" error: attribute: "user_identifier_type" message: "customer_identifier_type is not found in the payload" type: "MissingAttributeError" request_id: "nuJPehHC" missing_actiontype: summary: Action_type is missing in the payload value: status: "fail" error: attribute: "action_type" message: "Action_type is not found in the payload" type: "MissingAttributeError" request_id: "nuJPehHC" missing_deviceid: summary: Device_identifiers is missing in the payload value: status: "fail" error: attribute: "device_identifiers" message: "device_identifiers is missing in the payload" type: "MissingAttributeError" request_id: "jRwBuxdC" invalid_deviceid: summary: Action_type is missing in the payload value: status: "fail" error: attribute: "device_identifiers" message: "device identifier can only be in ['moe_gaid', 'push_id', 'unique_id', 'device_unique_id'] " type: "ValueError" request_id: "ZtrftlVn" '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 suspended. Please contact MoEngage team." type: "BlockedClient" request_id: "ofHUEaEQ" account_suspended: summary: 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: Account is temporarily suspended value: status: "fail" error: message: "Your account is temporarily suspended due to payment issues." 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 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 cannot exceed 128KB" type: "Payload too large" request_id: "VFzDwhwt" '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: "Server Error" request_id: "KovrwJiF" # SECTION 4: TRACKING /installInfo: get: tags: - Tracking summary: Track App Install description: | This API tracks the install attribution data in MoEngage, which you can then use to enhance your marketing automation campaigns on MoEngage. Install attribution tracking is a great way to improve your initial relationship with your user. Knowing how, where, and even more importantly, why a user installs your app allows you to get a better understanding of who your user is and how you should introduce them to your app. security: [] x-code-samples: - lang: Bash label: Android source: | curl -L -g -X GET 'https://api-0X.moengage.com/v1/installInfo?src=&appAttributionKey=&appId=&campaign_name=&publisher_name=&advertising_id=' - lang: Bash label: iOS source: | curl -L -g -X GET 'https://api-0X.moengage.com/v1/installInfo?src=&appAttributionKey=&appId=&campaign_name=&publisher_name=&idfv=' parameters: - name: publisher_name in: query schema: type: string description: Publisher name of the install. - name: campaign_name in: query schema: type: string description: Campaign name of the install. - name: src in: query required: true schema: type: string description: Partner name. - name: appId in: query required: true schema: type: string 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)**. - name: advertising_id in: query schema: type: string description: Google Advertising ID of the device on which the install was detected (for Android only). - name: idfv in: query schema: type: string description: IDFV of the iOS device on which the install was detected (for iOS only). - name: appAttributionKey in: query required: true schema: type: string description: Available on the MoEngage dashboard by navigating to **Settings > Analytics > Acquisition Tracking > Attribution Key**. responses: '200': description: | **Success** This response is returned when the request is processed successfully. content: application/json: schema: $ref: '#/components/schemas/GenericSuccess' '400': description: | **Bad Request** 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: $ref: '#/components/schemas/GenericError' '401': description: | **Unauthorized** This response is returned when the request does not have valid authentication credentials. content: application/json: schema: $ref: '#/components/schemas/GenericError' '403': description: | **Account Blocked** This response is returned when your MoEngage account is suspended or blocked. '413': description: | **Payload Size Exceeded** This response is returned when the payload size exceeds 128 KB. '429': description: | **Rate Limit Breach** This response is returned when the number of requests has exceeded the rate limit. '500': description: | **Internal Server Error** This response is returned when the system runs into an unexpected error. /integrations/authentication: post: security: - Basic Auth: [] tags: - Utilities summary: Test Connection API description: | This API validates if the entered endpoint details are valid. It verifies if the provided endpoint URL, workspace ID, and data key are accessible and responds without any errors. parameters: - name: MOE-APPKEY in: header 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 requestBody: required: true description: Set the Content-Type header to application/json. content: application/json: schema: $ref: '#/components/schemas/TestConnectionRequest' examples: cURL_Body: value: app_id: "********" app_secret: "**********" source: "test" region: "01" responses: '200': description: | Success. 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 denotes whether it was successful or not. **Example**: "status": "success", "status": "error" example: success app_name: type: string description: This field contains the workspace name of your MoEngage workspace example: Your_Workspace_ID example: status: "success" app_name: "Your_Workspace_ID" '401': description: | Authorization Failure. This response is returned when the authorization parameters are missing in the HTTP Auth Header. content: application/json: schema: type: object properties: status: type: string description: This field denotes the overall outcome of the API request (e.g., "success" or "fail"), allowing the client to quickly determine if the operation was completed as expected. example: fail error: type: object description: This field denotes a container object that holds specific technical details and context regarding the failure when the status is returned as "fail". properties: message: type: string description: This field denotes a human-readable description explaining the specific cause of the error, intended to help the developer or end-user understand what went wrong (e.g., "Missing required parameter"). example: "App Secret key mismatch. Please login to the dashboard to verify key" type: type: string description: This field denotes a machine-readable classification or category of the error (e.g., validation_error, authentication_error), which allows the client application to programmatically handle specific error scenarios. example: "Authentication required" request_id: type: string description: This field denotes a unique identifier assigned to this specific API transaction. example: "kKcQUqvo" example: status: "fail" error: message: "App Secret key mismatch. Please login to the dashboard to verify key" type: "Authentication required" request_id: "kKcQUqvo" # SECTION 6: FILE IMPORT /fileimports/trigger/{schedule_id}: post: servers: - url: 'https://fileimports-data-api-{dc}.moengage.com/v1.0/data' description: MoEngage File Imports 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: - Basic Auth: [] tags: - File Import summary: Trigger File Imports description: This API triggers scheduled file imports. You can trigger periodic imports to run using this API if the import has not expired and is in any of the following states- Scheduled, Successful, Partially Successful, and Failed. x-mint: content: | #### Rate Limit You can trigger this API once in every five minutes for a specific schedule_id. A Bad request response (400) response will be sent if this is exceeded. parameters: - name: schedule_id in: path required: true description: This field specifies the Import ID (the unique identifier for the import) of the import that needs to be triggered. You can find the Import ID in the MoEngage Dashboard on the Imports History page. Click **Actions** > **View import** to view the Import Details. You can also view the Import ID in the email notification received once the import has been set up. schema: type: string - name: MOE-APPKEY in: header 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 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." example: success, failure message: type: string description: This field contains information about whether the request was successful or not. example: Trigger Import Successful examples: success_response: summary: Successful request value: status: "success" message: "Triggered Import Successfully" '400': description: "This response is returned when the Import ID/Schedule ID is missing from the request or when the provided parameters are invalid. Also, this response is returned when the rate limit (one request in five minutes) is breached." content: application/json: schema: type: object properties: status: type: string example: fail description: This field contains the status of the request and specifies whether the request was successful. error_type: type: object description: "This field is present in the response when the Import/Schedule ID in the request is not found in the system (either because it is invalid or has been deleted)." message: type: string description: "This field contains information about whether the request was successful or not. " examples: invalid_scheduleid: summary: The Import ID (Schedule ID) in the Request is Invalid value: status: "fail" error_type: "NOT_FOUND" message: "This import is either deleted or expired." exceeded_user_limit: summary: The Number of Users Exceeds the Allowed Limit in the Request value: status: "fail" error_type: "ALREADY_EXISTS" message: "Import has run in the last 5 min." '401': description: This response is returned when the APP Key is invalid or missing, the password is incorrect, or there are other such authorization-related errors in the request. content: application/json: schema: type: object properties: title: type: string example: fail description: "This field is present in the response in the case of errors and contains the type of error." description: type: string description: "This field is present in the response in the case of errors and contains the error description." examples: incorrect_password: summary: Incorrect Password in the Header value: title: "AuthenticationInvalid" description: "Password (APP_KEY) doesn't match the one available on the dashboard. Kindly ensure the same APP_KEY available on the dashboard is used." missing_authorization_key: summary: Missing Authorization Key in the Header value: title: "HeaderMissing" description: "MOE-APPKEY is missing in Header" header_mismatch: summary: APP Key Mismatch in the Header value: title: "HeaderMismatch" description: "MOE_APPKEY doesn't match the Username (APP_KEY) used in Basic Auth authorization" '403': description: This response is returned when your MoEngage account has been blocked or suspended. content: application/json: schema: type: object properties: status: type: string example: fail error: type: object properties: message: type: string description: "This field contains information about whether the request was successful or not." type: type: string description: "This field is present in the response in the case of 403 errors and contains the error type." request_id: type: string description: "This field is present in the response in the case of 403 errors and contains the request-id." examples: account_blocked: summary: Your Account is Blocked value: status: "fail" error: message: "Your account is suspended. Please contact MoEngage team." type: "BlockedClient" request_id: "ofHUEaEQ" '404': description: This response is returned when the request contains the incorrect URL (when you try to access a resource that is not present). content: application/json: schema: type: object properties: status: type: string example: fail description: This field contains the status of the request and specifies whether the request was successful. message: type: string description: "This field contains information about whether the request was successful or not." examples: missing_resource: summary: Resource Not Found Error value: status: "fail" message: "Resource not found" '405': description: This response is returned when the request contains an unsupported method. For example, if you were to use the GET method instead of POST for this request, you would result in a 405 error. content: application/json: schema: type: object properties: status: type: string example: fail description: This field contains the status of the request and specifies whether the request was successful. message: type: string description: "This field contains information about whether the request was successful or not." examples: missing_resource: summary: Method Not Allowed Error value: status: "fail" message: "Method not allowed" '500': description: This response is returned when the system runs into an unexpected error. content: application/json: schema: type: object properties: title: type: string example: fail description: "This field is present in the response in the case of errors and contains the type of error." description: type: string description: "This field is present in the response in the case of errors and contains the error description." code: type: string description: This field is present in the response in the case of 5xx errors and contains the error code. examples: unknown_error: summary: Unknown Errors value: title: "Server Error" description: "An unexpected error was encountered while processing this request. Please contact MoEngage Team." code: "GlQhUzvM" /fileimports/import/status: post: servers: - url: 'https://fileimports-data-api-{dc}.moengage.com/v1.0/data' description: MoEngage File Imports 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: - Basic Auth: [] tags: - File Import summary: Import Details description: This API fetches the status at an import level. It can fetch the status of multiple imports but not the status of the files within the import. x-mint: content: | #### Rate Limit You can create 50 requests per minute. parameters: - name: MOE-APPKEY in: header 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ImportDetailsRequest' examples: all_the_filters_passed: summary: Sample cURL with all the filters passed in the API body. value: import_name: "test_import" import_type: - "USERS" - "EVENTS" - "AUX_DATA" date: start_date: "14/11/2024" end_date: "14/11/2024" format: "DD/MM/YYYY" schedule_type: - "PERIODIC" - "ONETIME" file_source: - "SFTP" - "S3" - "CSV" schedule_status: - "SUCCESSFUL" - "FAILED" - "PARTIAL_SUCCESS" - "SCHEDULED" - "PROCESSING" - "QUEUED" - "ARCHIVED" offset: "1" no_filters_passed: summary: Sample cURL with no filters passed in the API body. value: {} responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/ImportDetailsResponse' examples: success_response: summary: Successful request value: status: "success" total_count: 2 data: - import_id: "67348ff2e15wwe63bc257d9bf" import_name: "Special" last_run_status: "FAILED" import_type: "AUX_DATA" schedule_type: "ONETIME" import_source: "S3" custom_segment_config: {} aux_data_config: primary_key: "Email" retention_period: 15 retention_type: "DAYS" total_files: 0 processed_files: 0 total_rows: 0 processed_rows: 0 created_at: "2024-11-13T17:09:30.635000" last_run_at: "2024-11-13T17:09:32.024000" next_scheduled_at: "2024-11-13T11:39:30.619000" created_by_email: "abc@moengage.com" status: "FAILED" time_zone: "Asia/Calcutta" - import_id: "67348f4a55f435b54f109i9" import_name: "Duplicate_special" last_run_status: "FAILED" import_type: "AUX_DATA" schedule_type: "ONETIME" import_source: "S3" custom_segment_config: {} aux_data_config: primary_key: "Email" retention_period: 15 retention_type: "DAYS" total_files: 0 processed_files: 0 total_rows: 0 processed_rows: 0 created_at: "2024-11-13T17:06:42.722000" last_run_at: "2024-11-13T17:06:44.182000" next_scheduled_at: "2024-11-13T11:36:42.697000" created_by_email: "abc@moengage.com" status: "FAILED" time_zone: "Asia/Calcutta" offset: 1 more_files: false '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 description: This field denotes the status of the request. error_type: type: string description: "This field denotes the type of error occured" message: type: string description: "This field denotes the error message. " examples: invalid_date_format: summary: Invalid or Mismatched date format passed value: status: "FAILURE" error_type: "Invalid Date format" message: "The provided date format is either incorrect or doesn't match the entered dates. Please ensure both the dates and the format are valid." case_sensitivity: summary: Invalid bad request - Case sensitivity in parameter values passed in the API body value: success: false status_code: "400 Bad Request" data: "Unable to process the request" invalid_offset: summary: Bad request - Incorrect offset value passed value: status: "FAILURE" error_type: "Invalid Offset Value" message: "The offset value you have provided is not valid. Please review and correct the offset." date_range_exceeded: summary: Date range exceeds 30 days value: status: "FAILURE" error_type: "Difference exceeds 30 days" message: "Please note that only imports with a date difference of 30 can be displayed. Kindly adjust the dates accordingly." '401': description: This response is returned when the APP Key is invalid or missing, the password is incorrect, or there are other such authorization-related errors in the request. content: application/json: schema: type: object properties: title: type: string example: fail description: This field denotes the error title. description: type: string description: This field denotes error description. examples: missing_header: summary: MoeAPPkey missing, Invalid username, invalid password value: title: "HeaderMissing" description: "MOE-APPKEY is missing in Header" '404': description: This response is returned when the APP Key is invalid or missing, the password is incorrect, or there are other such authorization-related errors in the request. content: application/json: schema: type: object properties: status: type: string example: fail description: This field denotes the status of the request. data: type: string description: This field denotes the error description. examples: invalid_endpoint: summary: Resource not found value: status: "fail" data: "Resource not found." '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 description: This field contains the status of the request and specifies whether the request was a failure. 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_exceeded: summary: Rate limits exceeded value: status: "fail" error: message: "Rate limits exceeded, please try after some time" type: "Rate Limits Exceeded" request_id: "1234" /fileimports/import/run/history: post: servers: - url: 'https://fileimports-data-api-{dc}.moengage.com/v1.0/data' description: MoEngage File Imports 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: - Basic Auth: [] tags: - File Import summary: Import File Run History description: This API fetches the file processing status of each file contained in an import. The API request must contain either the import_name or the import_id. If you are not sure of the import_id or the import_name, you can use the [Import Details API](https://www.moengage.com/docs/api/file-import/import-details) to get the import details, which can be further used in the Import File Run History API. x-mint: content: | #### Rate Limit You can create 50 requests per minute. parameters: - name: MOE-APPKEY in: header 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 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FileRunHistoryRequest' responses: '200': description: Success. content: application/json: schema: $ref: '#/components/schemas/FileRunHistoryResponse' examples: success_response: summary: Successful request value: status: "success" total_count: "1" data: type: object items: type: object properties: id: "672561rr0abd2da34cf7f7df" file_name: "filename.csv" scheduled_at: "2024-11-14T12:31:31.713000" completed_at: "2024-11-14T12:32:09.942000" type: "AUX_DATA" file_size: "1544" file_status: "SUCCESSFUL" status_msg: "" total_rows: 10 skipped_rows: 0 updated_rows: 0 failed_rows: 0 aux_data_added_count: 10 aux_data_failed_count: 0 added_rows: 10 offset: 1 more_files: "false" '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 description: This field denotes the status of the request. error_type: type: object description: "This field denotes the type of error occured" message: type: string description: "This field denotes the error message. " examples: bad_request: summary: Bad request value: status: "FAILURE" error_type: "Import Doesn't Exist" message: "No import exist in the database with the given query parameters." invalid_date_format: summary: Date range not in ISO format value: status: "FAILURE" error_type: "Invalid Date format" message: "The date entered is not in the correct format. Please ensure you are using the ISO 8601 format which should look like this: YYYY-MM-DDTHH:MM:SS.ssssss. Please check this and try again." incorrect_offset_value: summary: Incorrect offset value passed value: status: "FAILURE" error_type: "Import Doesn't Exist" message: "No import exist in the database with the given query parameters." '401': description: This response is returned when the APP Key is invalid or missing, the password is incorrect, or there are other such authorization-related errors in the request. content: application/json: schema: type: object properties: title: type: string example: fail description: The title of the error. description: type: string description: The description of the error. examples: missing_header: summary: MOE-APPKEY is missing in Header value: title: "HeaderMissing" description: "MOE-APPKEY is missing in Header" '404': description: This response is returned when the APP Key is invalid or missing, the password is incorrect, or there are other such authorization-related errors in the request. content: application/json: schema: type: object properties: status: type: string example: fail description: This field contains the status of the request and specifies whether the request was a failure. data: type: string description: The description of the data. examples: invalid_endpoint: summary: Resource not found value: status: "fail" data: "Resource not found." '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_exceeded: summary: Rate limits exceeded value: status: "fail" error: message: "Rate limits exceeded, please try after some time" type: "Rate Limits Exceeded" request_id: "1234" # SECTION 7: BULK /transition/{Workspace_ID}: post: tags: - Bulk summary: Bulk Import Users and Events description: 'The Bulk Import API sends multiple user and event requests in batch to MoEngage, using a single API request. You can send a batch request of a maximum of 100 KB in a single API call.' x-mint: content: | All bulk API requests return a 200 response code. Debugging should be done on the user profile on the dashboard. #### User Identity Resolution In MoEngage, data ingestion uses an ID to create or update a user. For workspaces in MoEngage with [Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) enabled, you can use the Bulk Import API to create or update users using a specific identifier, such as a mobile number or email ID. These identifiers must be enabled for the workspace in the Identity Resolution dashboard. You can: * Create users through Server-to-Server Data APIs even when they do not have an ID (but have other identifiers). * Create a user or track events of a user when identifiers other than ID (for example, email ID or phone number) are known. #### Rate Limit A single bulk import API contains users, devices, and events together. Send a maximum of 60,000 users and 60,000 events per minute across all API requests. parameters: - name: Workspace_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 - 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 description: | **Types of Payload in Request Body** The sample cURL request for a Bulk Import API consisting of the following payloads: * **User payload**: Attribute parameters must contain at least one of the identifiers you have configured based on which users in MoEngage will be created, updated, or merged. * **Event payload**: Identifiers set up in the workspace must be mentioned within the _user_identifiers_ parameter, as shown in the below example where _moe_mobile_ is one of the identifiers in the workspace: ```json "user_identifiers":{ "moe_mobile":"{{Mobile_Number}}" } ``` content: application/json: schema: $ref: '#/components/schemas/BulkImportRequest' examples: Standard Example: summary: Combined User, Event, and Device Import value: type: "transition" elements: - type: "customer" customer_id: "AZ8TM" attributes: name: "qjDKn" first_name: "xSEdd" last_name: "UWbah" platforms: - platform: "iOS" active: "true" - type: "customer" customer_id: "9yt8q8" attributes: name: "5Np" first_name: "2irjN" last_name: "CH4Zo" platforms: - platform: "ANDROID" active: "true" - type: "customer" customer_id: "ONfYcF" attributes: name: "U92" first_name: "zgI63" last_name: "Dle4b" platforms: - platform: "web" active: "true" - type: "device" customer_id: "AZ8TM" device_id: "AZ8TM" attributes: brand: "{{model_bulk1}}" platform: "{{platform_bulk1}}" push_id: "pushid1991" - type: "device" customer_id: "9yt8q8" device_id: "9yt8q8" attributes: brand: "{{model_bulk1}}" platform: "{{platform_bulk1}}" push_id: "pushid2744" - type: "device" customer_id: "ONfYcF" device_id: "ONfYcF" attributes: brand: "{{model_bulk1}}" platform: "{{platform_bulk1}}" push_id: "pushid3546" - type: "event" customer_id: "ONfYc" actions: - action: "A6CO5" attributes: product: "Shirt" platform: "{{platform_bulk1}}" app_version: "839" user_time: "1712567385" current_time: "1712567385" - action: "wuDX8" attributes: product: "MacBook Air" brand: "Apple" platform: "iOS" app_version: "1.2.3" user_time: "1712567385" current_time: "1712567385" - type: "event" customer_id: "9yt8q8" actions: - action: "A6CO5" attributes: product: "Shirt" platform: "{{platform_bulk1}}" app_version: "1.2.3" user_time: "1712567385" current_time: "1712567385" - action: "Purchase" attributes: product: "MacBook Air" brand: "Apple" platform: "iOS" app_version: "1.2.3" user_time: "1712567385" current_time: "1712567385" - type: "event" customer_id: "ONfYcF" actions: - action: "A6CO5" attributes: product: "Shirt" platform: "{{platform_bulk1}}" app_version: "1.2.3" user_time: "1712567385" current_time: "1712567385" - action: "Purchase" attributes: product: "MacBook Air" brand: "Apple" platform: "iOS" app_version: "1.2.3" user_time: "1712567385" current_time: "1712567385" Properties as Date/Time: summary: Properties as Date/Time value: type: "transition" elements: - type: "customer" customer_id: "john@example.com" attributes: name: "John" platforms: - platform: "ANDROID" active: "true" - type: "event" customer_id: "john@example.com" device_id: "96bd03b6-defc-4203-83d3-dc1c73080232" actions: - action: "Added to Cart" attributes: product: "Mobile" color: "white" Brand: "Apple" platform: "iOS" app_version: "1.2.3" current_time: "2020-05-31T16:33:35Z" user_timezone_offset: 19800 - action: "Purchase" attributes: product: "MacBook Air" Brand: "Apple" platform: "iOS" app_version: "1.2.3" current_time: 1590404615 user_timezone_offset: 19800 Properties as Array: summary: Properties as Array value: type: "transition" elements: - type: "customer" customer_id: "OTBoS" attributes: name: "wtmNx" first_name: "bt016" last_name: "JPCUi" Array_attribute: - "one" - "two" platforms: - platform: "iOS" active: "true" - type: "device" customer_id: "OTBoS" device_id: "OTBoS" attributes: brand: "Mi" platform: "Windows" push_id: "pushid1186" - type: "event" customer_id: "OTBoS" actions: - action: "mOhrP" attributes: product: "Shoe" platform: "Windows" app_version: "581" user_time: "1712568861" current_time: "1712568861" Using User Identifiers: summary: Using User Identifiers value: type: "transition" elements: - type: "customer" attributes: moe_mobile: "{{Mobile_Number}}" first_name: "John" - type: "event" user_identifiers: moe_mobile: "{{Mobile_Number}}" actions: - action: "AddToCart" attributes: product: "MacBook Air" Brand: "Apple" 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: "This field denotes the attribute missing in the payload." 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: bad_request: summary: Bad 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: "oWvxnUuo" empty_elements: summary: Empty Body value: status: "fail" error: attribute: "elements" message: "'elements cannot be empty array" type: "MissingAttributeError" request_id: "oWvxnUuo" invalid_type: summary: Invalid Type value: status: "fail" error: attribute: "type" message: "'type in elements should be customer/event/device" type: "AttributeError" request_id: "oWvxnUuo" missing_customerid: summary: Customer ID is Missing value: status: "fail" error: attribute: "customer_id" message: "'customer_id not found in the payload" type: "MissingAttributeError" request_id: "oWvxnUuo" empty_action: summary: Empty Action value: status: "fail" error: attribute: "action" message: "'action cannot be empty Unicode string" type: "MissingAttributeError" request_id: "oWvxnUuo" malformed_json: summary: Element Data Type value: status: "fail" error: message: "'Could not decode the request body. The JSON was incorrect or not decoded as UTF-8." type: "Malformed JSON" request_id: "oWvxnUuo" # SECTION 8: WEBHOOKS components: securitySchemes: Basic Auth: type: http scheme: basic description: | Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'. - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**. - **Password**: Use your API Key, which you can find within the **Data** tile. **Note**: After you generate and save the Data API Key, DO NOT generate a new key unless there is a security breach. After you generate a different Data API key and save it, the authentication will start failing. You must update your existing data tracking. For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials). Data APIs also support OAuth 2.0. For more information, refer to [OAuth 2.0](/api/data/data-overview#oauth-2). OAuth 2.0: type: http scheme: bearer bearerFormat: JWT description: | Pass an OAuth 2.0 access token in the `Authorization` header as `Bearer `. OAuth 2.0 must be enabled for your Data APIs on the API Keys dashboard. To generate an access token, refer to [OAuth 2.0](/api/data/data-overview#oauth-2). schemas: 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. GenericError: 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., MissingAttributeError)." 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." PlatformObject: type: object properties: platform: type: string enum: [ANDROID, iOS, web] active: type: string enum: ["true", "false"] UserAttributes: type: object description: | A dictionary containing user attributes to add / update in the user profile. For example, to track custom attributes of different data types like string, numeric, boolean, and date, pass the following payload where points are a number, expiry_date is a date type attribute, and super_user is a boolean attribute. > **Note:** > * "id", "_id", and "" keywords are blocked and not to be used as user attribute names. > * You can not use "moe_" as a prefix while naming user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication. > For other attributes that are not listed below, use the key-value pairs that you intend to use. **Array Support** If you want to pass an attribute in an array, the appropriate syntax for that is: ```json "Array_attributeName":["abc","123"] ``` **Update Array Attributes** To update an existing array attribute rather than overwrite it, use `addValueToArrayField` and `removeValueFromArrayField` inside the `attributes` object of a Track User call: ```json { "customer_id": "user123", "attributes": { "addValueToArrayField": { "favorite_categories": ["shoes", "bags"] }, "removeValueFromArrayField": { "favorite_categories": ["hats"] } } } ``` * `addValueToArrayField` appends the given value(s) to an existing array attribute. * `removeValueFromArrayField` removes the given value(s) from an existing array attribute. * You can't add and remove the same attribute in one call. * You can't directly set an attribute and add/remove it in the same call. * Reserved MoEngage attributes (e.g. `platforms`) can't be used with these operators. properties: u_n: type: string description: Full name of the user. u_fn: type: string description: First name of the user. u_ln: type: string description: Last name of the user. u_gd: type: string description: Gender of the user. u_em: type: string format: email description: Email Address of the user (Standard). u_mb: type: string description: Mobile Number of the user (Standard). Example `918888444411`. uid: type: string description: 'A unique ID that the app has set for a user. This is a standard attribute where MoEngage provides the name, and the value is provided by the client.' u_bd: type: string format: date-time description: 'Birthdate of the user in ISO 8601 format (e.g., 2019-05-21T03:47:35Z).' moe_wa_subscription: type: boolean description: WhatsApp subscription status of a user. moe_em_unsub_categories: type: string description: Email Unsubscribed Categories. The list of email categories user has unsubscribed. push_preference: type: boolean description: Push Opt In Status (iOS).The push permission status of a user on an iOS device. moe_sub_w: type: boolean description: Web Push Subscription Status. The web push subscription status of a user. Use this to find your aggregate subscribers and users who unsubscribed after subscribing once. moe_spam: type: boolean description: Spam. Email Spam Attribute. The emails are not sent to the user when the set value is true. moe_unsubscribe: type: boolean description: Unsubscribe. Email Unsubscribe Attribute. Emails are not sent to the user when the set value is true. moe_hard_bounce: type: boolean description: Hard Bounce. Email Hard Bounce Attribute. The emails are not sent to the user when the set value is true. moe_sms_subscription: type: string description: SMS Subscription Status. An attribute which stores the SMS subscription status of the user. This will be used to see if a user is reachable based on certain values of the attribute. moe_email_optin_status: type: string enum: [DOUBLE_OPTED_IN, OPTED_OUT, OPT_IN_PENDING] description: | Email Opt-in Status. An attribute that stores the opt-in status of the user for the email channel. Supported values are: * `DOUBLE_OPTED_IN` * `OPTED_OUT` * `OPT_IN_PENDING` publisher_name: type: string description: Publisher Name. The name of the campaign publisher. This standard attribute can only be created through the Track User API and cannot be updated later. campaign_name: type: string description: Campaign Name. The name of the campaign. This standard attribute can only be created through the Track User API and cannot be updated later. u_l_a: type: integer format: int64 description: Last Seen. Time in epoch format (for example, `1767092989259`). This standard attribute can only be created through the Track User API and cannot be updated later. cr_t: type: integer format: int64 description: First Seen. Time in epoch format (for example, `1767092989259`). This standard attribute can only be created through the Track User API and cannot be updated later. geo: type: string description: 'Geolocation of the user as a string of latitude and longitude (for example, `88.90 89.00`).' moe_gaid: type: string description: Google Advertising ID (Android). A unique, resettable identifier provided by Google for ad tracking and attribution on Android devices. This standard attribute can only be created through the Track User API and cannot be updated later. advertising_identifier: type: string description: Advertising Identifier (iOS & Windows). A unique alphanumeric string used for ad tracking on iOS (IDFA) and Windows devices. This standard attribute can only be created through the Track User API and cannot be updated later. additionalProperties: true example: name: John points: 20 expiry_date: '2020-05-31T03:47:35Z' super_user: true user_persona: browsers CreateUserRequest: title: "User" type: object required: - type - customer_id properties: type: type: string description: 'This is used to identify the type of request. The value is case-sensitive and must be lowercase (`customer`). A value with different casing, such as `Customer`, is not accepted.' enum: [customer] customer_id: type: string description: | The unique identifier is used to identify/create a user in MoEngage. Not mandatory in [Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) enabled workspaces. If the User Identity Resolution feature is enabled in your workspace, the attribute parameters in the payload must contain at least one of the identifiers you have activated in your workspace based on which users in MoEngage will be created, updated, or merged. In the following example, moe_mobile is one of the identifiers in the workspace and is passed in attributes: ```json { "type": "customer", "attributes": {"moe_mobile": "{{Mobile_Number}}", "first_name": "John" } } ```' update_existing_only: type: boolean default: false description: | This field should be passed in the request when only existing users in MoEngage should be updated. **If this value is passed as true:** 1. Only those users for whom the customer_id from the request payload matches the customer identifier in MoEngage will be updated. 2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), they will not be created. **If this value is passed as false:** 1. The user attributes will be updated with the values present in the payload for existing customers. 2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), a new customer will be created in the system with the details specified in the payload. attributes: $ref: '#/components/schemas/UserAttributes' platforms: type: array description: "List of dictionaries with the associated platforms out of ANDROID, iOS, and web and their status." items: $ref: '#/components/schemas/PlatformObject' unset_attributes: type: array description: | Use this field to clear one or more existing user attributes, matched either by exact name or by pattern. Attributes matched by any rule in the array are removed from the user profile. ```json { "customer_id": "user123", "unset_attributes": [ { "type": "equals", "attr": "first_name", "case_sensitive": false }, { "type": "prefix", "attr": "temp_" } ] } ``` * System/reserved attributes are protected and can't be unset this way. items: $ref: '#/components/schemas/UnsetAttributeRule' UnsetAttributeRule: type: object required: - type - attr properties: type: type: string enum: [equals, prefix, suffix, contains] description: 'This field specifies how `attr` is matched against existing user attribute names.' attr: type: string description: 'This field specifies the attribute name (for `equals`) or the pattern (for `prefix`, `suffix`, `contains`) to match against.' case_sensitive: type: boolean default: true description: 'This field specifies whether the match is case-sensitive. Optional, defaults to true.' IdentifierObject: type: object properties: identifier_type: type: string enum: [customer_id, moengage_id] description: This field specifies the identifier type. Identifier types can either be customer_id (ID field in the User Profile) or moengage_id (the MoEngageID of the user in the User Profile). Allowed values are "moengage_id", "customer_id". example: customer_id identifier: type: string description: This field specifies the unique identifier that identifies the user. example: 6416d1a318r98264512c0f89 GetUserRequest: type: object required: - data properties: data: type: object description: | Wrapper object that contains the user identifiers to look up. The API expects `identifiers` inside this object, not at the root of the JSON body. required: - identifiers properties: identifiers: type: array description: | This field is used to specify the identifiers for the users for whom the data needs to be fetched. Structure: ```json "data": { "identifiers": [ { "identifier_type": "customer_id", "identifier": "" }, { "identifier_type": "id", "identifier": "" }, ...{} ] } ``` items: $ref: '#/components/schemas/IdentifierObject' user_fields_to_export: type: array items: type: string description: This field is used to specify the fields that need to be fetched for the user specified in Identifiers. Tracked standard user attributes and custom attributes can be fetched using this API. For the list of tracked standard attributes in MoEngage, refer to [User Attributes](#user-attributes). example: ["last_name", "customer_id", "name"] GetUserResponse: type: object properties: status: type: string example: success type: type: string example: export_users data: type: object properties: users_not_found: type: array items: $ref: '#/components/schemas/IdentifierObject' users: type: array items: type: object properties: user_attributes: type: object additionalProperties: true example: last_name: Doe customer_id: john_doe id: 62e79fb15ada55x123g987bu error: type: object description: | This field is present in the response only in the case of an error and contains the error details. This is the structure: ```json { "attribute": "", "message": "", "type": "", "request_id": "" } ``` properties: attribute: type: string description: | This field contains the name of the request attribute causing the error. For example, "attribute": "identifiers" implies that the identifiers request attribute is causing the error. message: type: string description: This field contains the error message. type: type: string description: | This field contains the error type. For example, "type": "Malformed JSON" implies that the JSON in the request is incorrectly formed. request_id: type: string description: This field denotes the request-id for which the error response is being returned. MergeUserRequest: type: object properties: merge_data: type: array description: | This field contains the list of UID pairs of the users who are to be merged. Example: ```json { "merge_data": [ // All the different pairs of users to merge { "merged_user": "", // This user will merge into below user "retained_user": "" // Above user will merge into this user }, { "merged_user": "", // This user will merge into below user "retained_user": "" // Above user will merge into this user } ] } ``` * Every object in the Array contains a pair of UID strings - the ‘merged_user’ and the ‘retained_user’. * UID is the unique identifier for a user maintained by you. MoEngage stores this identifier in the ID attribute in the user profile. * If the merging of any user fails in the array, it will skip that object and continue with others. items: type: object properties: merged_user: type: string description: | The user ID to be merged and then deleted. All the data of this user will merge into the retained user. Merged users will be deleted after 30 days of inactivity. If MoEngage receives any event or user property for the merged user after the merging activity, the merged user will not be deleted. The following happens in MoEngage post-user merging: * In the user profile, all events of the last 30 days are moved from the merged user to the retained user. * Segmentation and campaign move all data from merged user to retained user. retained_user: type: string description: | The user ID that will remain and absorb the merged user's data. The merged user’s attributes and associated devices are mapped to the retained user post-merge. Reachability calculation is done for the retained user based on the devices. All of the user attributes of the merged user are moved to the retained user. If an attribute is present for the retained user and the same attribute is not for the merged user, the attribute is retained for the retained user. DeleteUserRequest: type: object description: 'Request body to delete users. Based on the Get User API structure.' properties: identifiers: type: array description: Array of user identifiers to delete. items: $ref: '#/components/schemas/IdentifierObject' 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. **Array Support** If you want to pass an attribute in an array, the appropriate syntax for that is: ```json "Array_attributeName":["abc","123"] ``` example: price: 3999 departure_date: '2019-05-21T03:47:35Z' premium_seat: true platform: type: string enum: [ANDROID, iOS, web, TV, unknown] description: | Used to identify the platform on which the event happened. Allowed values are ANDROID, iOS, web, or unknown. **Note**: 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. moe_os_type: type: string enum: [ROKU, WebOS, AndroidTV, tvOS, Tizen, FireOS, VizioTV, Xbox] description: | Used to identify the operating system of the TV. **Note**: Ensure that you pass this parameter only when the platform is TV. Following are the valid moe_os_type accepted in MoEngage: * ROKU for RokuTV * WebOS for LGTV * AndroidTV for AndroidTV * tvOS for AppleTV * Tizen for SamsungTV * FireOS for FireTV * VizioTV for VizioTV * Xbox for Xbox 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. 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 (10 digits) (for example - 1590404615) current_time: oneOf: - type: number - type: string description: | UTC time at which the event happened. 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 (10 digits) (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`. * 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. * Include `user_timezone_offset` in your request only if you have accurate timezone information for each user, as incorrect info could disrupt event timelines in the user profile. **Note:** 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 do not 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. CreateEventRequest: title: "Event" type: object required: - type - customer_id - actions properties: type: type: string description: 'This is used to identify the type of request. The allowed value is `event`. The value is case-sensitive and must be lowercase. A value with different casing, such as `Event`, is not accepted.' 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. **User Identity Resolution:** If the [User Identity Resolution](/user-guide/data/user-data/unified-identity-identity-resolution) feature is enabled in your workspace, identifiers set up in the workspace must be mentioned within the user_identifiers parameter. additionalProperties: true example: moe_mobile: "+9198765xxxxx" actions: type: array description: List of events to be tracked for the user. items: $ref: '#/components/schemas/EventAction' DeviceAttributes: type: object description: This field contains the device attributes to add or update in the device profile. required: - platform - push_id properties: model: type: string description: This field denotes the model of the device. platform: type: string enum: [ANDROID, iOS, web, TV] example: ANDROID description: This field denotes the platforms where the device is supported. Using unsupported values may result in an API response of 400. push_id: type: string description: This field denotes the Push token of the device. When you pass a push token using this API, reachability is only updated if the device is currently marked as _Installed_. If a device is marked as _Uninstalled_, updating the `push_id` or `moe_push_opted` using Track Device API will not affect its reachability (it will remain Unreachable). To change a device's status back to _Installed_, the MoEngage SDK must actively track the device. moe_push_opted: type: string enum: ["True", "False"] description: This field denotes the opt-in status of the device of the user. moe_push_provisional_opted: type: string description: This field denotes the provisional push opt-in status of the user. Know more about provisional push [here](/user-guide/campaigns-and-channels/mobile-push/notification-features-and-behavior/ios-push-permission-and-reachability). app_version: type: string description: This field denotes the version of the app on the device. os_version: type: string description: This field denotes the device's operating system version. moe_gaid: type: string description: This field denotes the unique advertising identifier for Android devices to measure user behavior and campaign performance. idfv: type: string description: This field denotes the unique advertising identifier for iOS devices. CreateDeviceRequest: title: "Device" type: object required: - type - customer_id - device_id - attributes properties: type: type: string enum: [device] description: 'This field denotes the type of request. The supported value is `device`. The value is case-sensitive and must be lowercase. A value with different casing, such as `Device`, is not accepted.' customer_id: type: string description: 'This field denotes the unique identifier used to identify a user in MoEngage. Note that devices can be created for existing users only.' device_id: type: string description: 'This field denotes the unique identifier used to identify the device associated with a user in MoEngage. If your app is integrated with MoEngage SDK, the SDK assigns a unique device_id to the devices of your end-users. If your app is not integrated with MoEngage SDK, you can use unique alphanumeric values or other device attributes such as Push token, GAID/IDFV to assign unique device_id values to devices of your user.' attributes: $ref: '#/components/schemas/DeviceAttributes' DeviceOptOutRequest: type: object required: - user_identifier_type - user_identifier_value - action_type properties: user_identifier_type: type: string description: This field denotes the type of user identifier. user_identifier_value: type: string description: This field denotes the user identifier. action_type: type: string enum: [block, unblock] description: This field denotes the type of action to be achieved using this API. reason: type: string description: This field denotes the reason for blocking or unblocking a device. client_reference_id: type: string description: This field denotes the reference ID of the user. device_identifiers: type: array description: | This field denotes the device identifiers associated with the device you intend to block or unblock. Supported values are: * `unique_id` (unique_id) * `device_unique_id` (device_id) * `push_id` (push_id) * `moe_gaid` (GAID) Note: * If you do not pass this value, the API blocks/unblocks all current devices of the user. * Ensure to pass any one of the device identifiers for a particular device. * When passing the device identifiers within the array, ensure to explicitly define each of them. items: type: object properties: GAID: type: string description: This field denotes the unique advertising identifier for Android devices to measure user behavior and campaign performance. IDFV: type: string description: This field denotes the unique advertising identifier for iOS devices. unique_id: type: string device_unique_id: type: string description: This field denotes the unique identifier used to identify the device associated with a user in MoEngage. push_id: type: string description: This field denotes the Push token of the device. TestConnectionRequest: type: object required: - app_id - app_secret - source - region properties: app_id: type: string description: 'Your MoEngage Workspace ID.' app_secret: type: string description: 'Your MoEngage Data API Key.' source: type: string description: 'The tool from where you are sending the request.' example: test region: type: string description: 'Your MoEngage region (e.g., "01" for DC-01).' example: "01" ImportDetailsRequest: type: object properties: import_type: type: string enum: [USERS, EVENTS, AUX_DATA] description: 'This field denotes the type of data to be imported.' date: type: object description: | This field denotes the file processing date. Supported values are: * `start_date` * `end_date` * `format` If this field is not passed, the API will respond with details of all the files corresponding to the import_id or import_name passed and in accordance to the offset and limit values. Supported date time formats are: * `"datetime_format": "YYYY-MM-DD"` (2022-01-22) * `"datetime_format": "YYYY/MM/DD"` (2022/01/22) * `"datetime_format": "DD/MM/YYYY"` (22/01/2022) * `"datetime_format": "DD-MM-YYYY"` (22-01-2022) * `"datetime_format": "DD-MM-YYYY hh:mm:ss"` (31-12-2022 12:10:33) * `"datetime_format": "DD/MM/YYYY hh:mm:ss"` (31/12/2022 12:10:33) * `"datetime_format": "YYYY-MM-DD hh:mm:ss"` (2019-02-22 17:54:14) * `"datetime_format": "YYYY/MM/DD hh:mm:ss"` (2019/02/22 17:54:14) properties: # <--- Use 'properties' directly for objects, NO 'items' start_date: type: string format: date-time description: The start date of the import. end_date: type: string format: date-time description: The end date of the import. format: type: string description: The format of the date. schedule_type: type: string enum: [PERIODIC, ONETIME] description: 'This field denotes the type of import schedule.' file_source: type: string enum: [SFTP, S3, CSV] description: 'This field denotes the file source of the import.' schedule_status: type: string enum: [SUCCESSFUL, FAILED, PARTIAL_SUCCESS,SCHEDULED, PROCESSING, QUEUED, ARCHIVED ] description: | This field denotes the import schedule status. * PARTIAL_SUCCESS is displayed when all rows in the files are not processed successfully. * QUEUED is displayed when the import is queued to be processed next. * ARCHIVED is displayed when the import is archived. import_name: type: string description: "This field denotes the name of the import." offset: type: integer description: | 'API responds with a maximum of 50 file details in a single response. For example, if there are a total of 150 files that are part of the API response, then: * Offset = 1 will fetch the details of the first 50 files * Offset = 2 will fetch the file details of the next 50 imports * Offset = 3 will fetch the import details of the last 50 imports * If offset is not passed in the request body, the API response will consider offset = 1. You can refer to the total_count parameter in the response to understand how many total files are part of the response. OR If the API responds with more_files = true, it indicates that there are more files that are not part of the current response for which another API request must be made with offset +1.' default: 1 ImportDetailsResponse: type: object properties: status: type: string description: "This field denotes the status of the API response." example: success total_count: type: integer description: "This field denotes the total count of the imports in the response." example: 1 data: type: array description: "This field contains the import data details." items: type: object properties: import_id: type: string description: This field denotes the unique ID of the import. import_name: type: string description: This field denotes the unique name of the import. last_run_status: type: string description: This field denotes the latest sync status of the import. format: date-time import_type: type: string description: This field denotes the import type. enum: [USERS, EVENTS, AUX_DATA] schedule_type: type: string description: This field denotes the file type. enum: [ONETIME, PERIODIC] import_source: type: string description: "This field denotes the source of import." enum: [S3, SFTP, CSV] custom_segment_config: type: array description: This field contains details about the custom segment. items: type: object properties: id: type: string description: This field denotes the custom segment ID. name: type: string description: This field denotes the unique name of the custom event. type: type: string description: This field denotes the type of custom segment. user_id_column: type: string description: This field denotes the attribute selected as the identifier. aux_data_config: type: array description: This field contains details about the auxiliary data. items: type: object properties: primary_key: type: string description: This field denotes the attribute used as the auxiliary data import ID. retention_period: type: integer description: This field denotes the number of days, weeks, and months (to be read with retention_type). retention_type: type: string description: The field denotes retention type. enum: [DAYS, WEEKS, MONTHS] total_files: type: integer description: This field denotes the total number of files in the import. processed_files: type: integer description: This field denotes the total number of processed files in the import. total_rows: type: integer description: This field denotes the total number of rows across all files. processed_rows: type: integer description: This field denotes the total number of processed rows across all files. created_at: type: integer description: This field denotes the date at which the import is created. last_run_at: type: string description: This field denotes the date on which the import was last run. format: date time next_scheduled_at: type: string description: This field denotes the date on which the import is next scheduled. format: date time created_by_email: type: string description: This field denotes the email ID of the team member who created the import. status: type: string description: This field denotes the import status. time_zone: type: string description: This field denotes the timezone of the workspace. offset: type: integer description: | This field denotes the pagination value of the imports. For example, if there are 100 imports to be fetched in the response: * Offset = 1 will return the first 50 imports * Offset = 2 will return the next 50 import details more_files: type: string description: This field indicates if there are more files. For example, if there are 100 imports and offset = 1, 50 imports will be returned with more_file = true to indicate that offset = 2 must be passed to get the next 50 imports. FileRunHistoryRequest: type: object required: - import_id - import_name properties: import_id: type: string description: 'The unique identifier is used to identify the import. You can find this on the Data Imports page of the MoEngage dashboard. Data > Data Imports > Click the ellipsis icon for an import > View. The import_id or the import_name must be passed.' import_name: type: string description: 'This field denotes the name of the import.The import_id or import_name has to be passed. If both are passed, import_id takes precedence.' date: type: object description: | This field denotes the file processing date. Supported values are: * `start_date` * `end_date` * `format` If this field is not passed, the API will respond with details of all the files corresponding to the import_id / import_name passed and in accordance to the offset and limit values. Supported date time formats are: * `"datetime_format": "YYYY-MM-DD"` (2022-01-22) * `"datetime_format": "YYYY/MM/DD"` (2022/01/22) * `"datetime_format": "DD/MM/YYYY"` (22/01/2022) * `"datetime_format": "DD-MM-YYYY"` (22-01-2022) * `"datetime_format": "DD-MM-YYYY hh:mm:ss"` (31-12-2022 12:10:33) * `"datetime_format": "DD/MM/YYYY hh:mm:ss"` (31/12/2022 12:10:33) * `"datetime_format": "YYYY-MM-DD hh:mm:ss"` (2019-02-22 17:54:14) * `"datetime_format": "YYYY/MM/DD hh:mm:ss"` (2019/02/22 17:54:14) properties: # <--- Use 'properties' directly for objects, NO 'items' start_date: type: string format: date-time description: The start date of the import. end_date: type: string format: date-time description: The end date of the import. format: type: string description: The format of the date. file_status: type: array description: 'This field denotes the status of files contained in an import.' items: type: string enum: [SUCCESSFUL, FAILED, PARTIAL_SUCCESS, PROCESSING, QUEUED, WAITING] offset: type: integer description: | 'API responds with a maximum of 50 file details in a single response. For example, if there are a total of 150 files that are part of the API response, then: * Offset = 1 will fetch the details of the first 50 files * Offset = 2 will fetch the file details of the next 50 imports * Offset = 3 will fetch the import details of the last 50 imports * If offset is not passed in the request body, the API response will consider offset = 1. You can refer to the total_count parameter in the response to understand how many total files are part of the response. OR If the API responds with more_files = true, it indicates that there are more files that are not part of the current response for which another API request must be made with offset +1.' default: 1 FileRunHistoryResponse: type: object properties: status: type: string description: "This field denotes the status of the API response." example: success total_count: type: integer description: "This field denotes the total count of the files fetched based on the API request." example: 1 data: type: array description: "This field contains the file data details." items: type: object properties: id: type: string description: This field denotes the unique ID of the file. file_name: type: string description: This field denotes the name of the file. scheduled_at: type: string description: This field denotes the time at which the file is scheduled. format: date-time completed_at: type: string description: This field denotes the time at which the file is completed. format: date-time type: type: string description: This field denotes the file type. enum: [USERS, EVENTS, AUX_DATA] file_size: type: string description: "This field denotes the file size in terms of the number of rows in the file." file_status: type: string description: This field denotes the file status. enum: [SUCCESSFUL, FAILED, PARTIAL_FAILURE, QUEUED] status_msg: type: string description: This field denotes the error message in case of failure or partial failure. total_rows: type: integer description: This field denotes the total number of rows in the file. skipped_rows: type: integer description: This field denotes the skipped number of rows in the file. updated_rows: type: integer description: This field denotes the updated number of rows in the file. failed_rows: type: integer description: This field denotes the number of rows in the file that failed to process. aux_data_added_count: type: integer description: This field denotes the number of rows added as auxiliary data. This is applicable to auxiliary data. aux_data_failed_count: type: integer description: This field denotes the number of rows that failed to process. This is applicable to auxiliary data. added_rows: type: integer description: This field denotes the total number of rows added from the file. offset: type: integer description: | This field denotes the pagination value of the imports. For example, if there are 100 imports to be fetched in the response: * Offset = 1 will return the first 50 imports * Offset = 2 will return the next 50 import details more_files: type: string description: This field indicates if there are more files. For example, if there are 100 imports and offset = 1, 50 imports will be returned with more_file = true to indicate that offset = 2 must be passed to get the next 50 imports. BulkImportRequest: type: object required: - type - elements properties: type: type: string enum: [transition] description: This is used to identify the type of request. This field is case-sensitive. Follow the case as in the example when passing the value in the request. elements: type: array enum: [customer, event, device] description: List of data points (events and customers) to track. The type field in this list denotes whether the information is for a customer or an event. This field is case-sensitive. Follow the case as in the example when passing the value in the request. items: oneOf: - $ref: '#/components/schemas/CreateUserRequest' - $ref: '#/components/schemas/CreateEventRequest' - $ref: '#/components/schemas/CreateDeviceRequest' StreamsWebhookPayload: type: object properties: app_name: { type: string } source: { type: string, example: "MOENGAGE" } moe_request_id: { type: string, format: uuid } events: type: array items: type: object properties: event_name: { type: string } event_code: { type: string } event_uuid: { type: string, format: uuid } event_time: { type: integer, format: int64, description: "Epoch time in seconds" } event_type: { type: string, enum: [CAMPAIGN_EVENT, USER_ACTION_EVENT] } event_source: { type: string, example: "MOENGAGE" } uid: { type: string, description: "MoEngage customer_id" } event_attributes: type: object additionalProperties: true user_attributes: type: object additionalProperties: true device_attributes: type: object additionalProperties: true