> ## Documentation Index > Fetch the complete documentation index at: https://moengage-sdk-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Bulk Import Users and Events > Use the Bulk Import API to send, to MoEngage, in batch multiple user and event requests using a single API request. You can send a batch request of a maximum of 100 kB in a single API call. 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 dropdown. ### Array Support To view the appropriate syntax to pass an attribute in an array, select **array\_support** from the dropdown ### User Identity Resolution In MoEngage, data ingestion uses an ID to create or update a user. For workspaces in MoEngage with [Identity Resolution](https://help.moengage.com/hc/en-us/articles/24050999467284-Unified-Identity-Identity-Resolution) enabled, Bulk Import API can be used to create or update users using a specific identifier, such as a mobile number or email ID, these identifiers need to be enabled for the workspace in 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: ```json "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 dropdown. ## OpenAPI ````yaml /api/data/data.yaml post /transition/{Workspace_ID} openapi: 3.0.3 info: title: MoEngage Data APIs version: '1.0' description: >- This is a comprehensive OpenAPI specification for MoEngage's Data APIs, including User, Event, and Device management. It's designed to power an interactive API playground on your new documentation site. servers: - url: https://api-0{dc}.moengage.com/v1 description: MoEngage Core API Server variables: dc: default: '1' description: >- The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](https://help.moengage.com/hc/en-us/articles/360057030512-Data-Centers-in-MoEngage). Your MoEngage Data Center (DC) can be 1, 2, 3, 4,5, 6. enum: - '1' - '2' - '3' - '4' - '5' - '6' security: - Authentication: [] tags: - name: User description: Operations for creating, updating, retrieving, and managing user profiles. - name: Event description: Operations for tracking user events. - name: Device description: Operations for managing user devices. - name: Tracking description: Endpoints for tracking attribution and installs. - name: Utilities description: Utility endpoints for testing connections. - name: File Imports description: Operations for managing asynchronous file imports. - name: Bulk description: Operations for importing users and events in bulk. - name: Webhooks description: Incoming webhook specifications from MoEngage. paths: /transition/{Workspace_ID}: post: tags: - Bulk summary: Bulk Import Users and Events description: >- Use the Bulk Import API to send, to MoEngage, in batch multiple user and event requests using a single API request. You can send a batch request of a maximum of 100 kB in a single API call. parameters: - name: Workspace_ID in: path required: true description: >- This is the Workspace ID of your MoEngage account that has to be passed along with the request. You can find your MoEngage Workspace ID 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 content: application/json: schema: $ref: '#/components/schemas/BulkImportRequest' examples: sample_cURL: 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: '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' example_payload: summary: Example Payload 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 array_support: summary: Array Support 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: '1712568861457' current_time: '1712568861457' user_identity_resolution: summary: User Identity Resolution 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: 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: 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 components: schemas: 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' 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. CreateUserRequest: title: User type: object required: - type - customer_id properties: type: type: string 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. enum: - customer customer_id: type: string description: > The unique identifier is used to identify/create a user in MoEngage. Not mandatory in [Identity Resolution](https://help.moengage.com/hc/en-us/articles/24050999467284-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' CreateEventRequest: title: Event type: object required: - type - customer_id - actions properties: type: type: string description: >- This is used to identify the type of request. Allowed value is event.This field is case-sensitive. Follow the case as in the example when passing the value in the request. enum: - event customer_id: type: string description: >- Identifier to identify or create a user in MoEngage. Not mandatory in Identity resolution enabled workspaces. device_id: type: string description: >- Device_id in event payload is optional. The default value is the customer_id value. The value is used to map events to specific devices. user_identifiers: type: object description: >- Required if Identity Resolution is enabled and customer_id is not provided. additionalProperties: true example: moe_mobile: '+919876543210' actions: type: array items: $ref: '#/components/schemas/EventAction' 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. Supported value is: device. This field is case-sensitive. When passing the value in the request, follow the case as in the example. 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' 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. 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` additionalProperties: true example: name: John points: 20 expiry_date: '2020-05-31T03:47:35Z' super_user: true user_persona: browsers PlatformObject: type: object properties: platform: type: string enum: - ANDROID - iOS - web active: type: string enum: - 'true' - 'false' EventAction: type: object required: - action properties: action: type: string description: The name of the event to be tracked. attributes: type: object additionalProperties: true description: A dictionary containing event attributes to track with the event. example: price: 3999 departure_date: '2019-05-21T03:47:35Z' premium_seat: true platform: type: string enum: - ANDROID - iOS - web - unknown description: >- Used to identify the platform on which the event happened. Allowed values are ANDROID, iOS, web, or unknown. app_version: type: string description: App Version of the app on which the event originated. user_time: oneOf: - type: number - type: string description: > Local time at which the event happened. (Epoch seconds or ISO 8601 string). This field lets the system identify the local system time for when the event happened. Acceptable formats for user_time: * ISO 8601 (for example - 2020-05-31T16:33:35Z) * Epoch time in seconds (for example - 1590404615) current_time: oneOf: - type: number - type: string description: > UTC time at which the event happened. (Epoch seconds or ISO 8601 string). This field is necessary to specify the UTC time of the event. Acceptable formats for current_time include: * ISO 8601 (for example - 2020-05-31T16:33:35Z) * Epoch time in seconds (for example - 1590404615) user_timezone_offset: type: number description: > The difference in time between UTC and the local system time in a particular time zone. All time zones are defined by their offset from UTC. The offset is expressed as either UTC- or UTC+. * user_timezone_offset should have a value in seconds which can be between -54000 to 54000. For example, for IST (UTC+0530), "user_timezone_offset" will be 19800. * This field is crucial for establishing the `User_time` or `Current_time`. * This field should contain a numerical value between -54000 and 54000, representing the local timezone’s offset from UTC in seconds. * If the field is absent, MoEngage gets this information from the internal system in the sequence as follows: * The user profile’s timezone is taken into consideration. * If the user profile’s timezone is not present, the App/account’s timezone is considered. * In cases where neither is present, the UTC timezone is used. * Only include `User_timezone_offset` in your request if you have accurate timezone information for each user, as incorrect info could disrupt event timelines in the user profile. 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 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. 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](https://help.moengage.com/hc/en-us/articles/22865898059668-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. securitySchemes: Authentication: type: http scheme: basic description: > This authentication parameter, used for access control, must be passed along with the request. The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below: `{"Authorization: Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}` The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps: 1. Navigate to Settings -> Account -> APIs. 2. Copy the following details: * **Username:** Under Workspace ID (earlier app id), click the copy icon to copy the username. * **Password:** In the **API keys** section, click the copy icon in the **Data** tile to copy the API key. Use these details to authenticate the API requests. ````