Skip to main content
POST
/
transition
/
{Workspace_ID}
curl --request POST \
  --url https://api-0{dc}.moengage.com/v1/transition/{Workspace_ID} \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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": "1712567385726",
          "current_time": "1712567385726"
        },
        {
          "action": "wuDX8",
          "attributes": {
            "product": "MacBook Air",
            "brand": "Apple"
          },
          "platform": "iOS",
          "app_version": "1.2.3",
          "user_time": "1712567385726",
          "current_time": "1712567385726"
        }
      ]
    },
    {
      "type": "event",
      "customer_id": "9yt8q8",
      "actions": [
        {
          "action": "A6CO5",
          "attributes": {
            "product": "Shirt"
          },
          "platform": "{{platform_bulk1}}",
          "app_version": "1.2.3",
          "user_time": "1712567385726",
          "current_time": "1712567385726"
        },
        {
          "action": "Purchase",
          "attributes": {
            "product": "MacBook Air",
            "brand": "Apple"
          },
          "platform": "iOS",
          "app_version": "1.2.3",
          "user_time": "1712567385726",
          "current_time": "1712567385726"
        }
      ]
    },
    {
      "type": "event",
      "customer_id": "ONfYcF",
      "actions": [
        {
          "action": "A6CO5",
          "attributes": {
            "product": "Shirt"
          },
          "platform": "{{platform_bulk1}}",
          "app_version": "1.2.3",
          "user_time": "1712567385726",
          "current_time": "1712567385726"
        },
        {
          "action": "Purchase",
          "attributes": {
            "product": "MacBook Air",
            "brand": "Apple"
          },
          "platform": "iOS",
          "app_version": "1.2.3",
          "user_time": "1712567385726",
          "current_time": "1712567385726"
        }
      ]
    }
  ]
}
'
{
  "status": "success",
  "message": "Your request has been accepted and will be processed soon."
}

​
Rate Limit

A single bulk import API contains users, devices, and events together. Send a maximum of 10,000 users and 30,000 events per minute across all API requests.
All bulk API requests return a 200 response code. Debugging should be done on the user profile on the dashboard.

​
Example Payload

To view the sample API request, select example_payload from the drop-down (on the right side).

​
Array Support

To view the appropriate syntax to pass an attribute in an array, select array_support from the drop-down (on the right side).

​
User Identity Resolution

In MoEngage, data ingestion uses an ID to create or update a user. For workspaces in MoEngage with 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.

​
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:
"user_identifiers":{
"moe_mobile":"{{Mobile_Number}}"
}
To view the Bulk Import API that consists of payloads for users and events, select user_identity_resolution from the drop-down (on the right side).

Authorizations

​
Authorization
string
header
required

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.

Headers

​
X-Forwarded-For
string

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.

Example:

"203.0.113.195"

Path Parameters

​
Workspace_ID
string
required

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).

Body

application/json
​
type
enum<string>
required

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.

Available options:
transition
​
elements
(User · object | Event · object | Device · object)[]
required

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.

Response

This response is returned when the request is processed successfully.

​
status
string

This field contains the status of the request and specifies whether the request was successful.

Example:

"success"

​
message
string
Example:

"Your request has been accepted and will be processed soon."