openapi: 3.0.0
info:
  title: MoEngage - Data APIs
  description: >-
    Data APIs are used to send user data (user properties and events) from your
    servers to MoEngage.


    Data API is a collection of the following APIs


    - User API

    - Event API

    - Bulk Import API
        

    Learn More -
    [https://developers.moengage.com/hc/en-us/articles/4404674776724-Overview](https://developers.moengage.com/hc/en-us/articles/4404674776724-Overview)
  version: 1.0.0
servers:
  - url: https://api-{{0x}}.moengage.com
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
paths:
  /v1/customer/{APP ID}:
    post:
      tags:
        - General
      summary: 1. User API
      description: >-
        User API allows you to add/update users and user properties in MoEngage.
        You can create a new user, a new user property or update updating
        existing user properties of users. It includes customer_id (Unique
        Identifier of User) and other User Attributes(ex: name, age etc.. ).


        **Base URL**


        | Data Center | Replace {{OX}} with |

        | --- | --- |

        | DATA_CENTER_1 | 01 |

        | DATA_CENTER_2 | 02 |

        | DATA_CENTER_3 | 03 |


        **Request Body**


        | Key | Datatype | Mandatory Field | Description |

        | --- | --- | --- | --- |

        | type | String | Yes | This is used to identify the type of request. |

        | customer_id | String | Yes | The unique identifier is used to
        identify/create a user in MoEngage. Please refer to this section for
        more information on customer_id. |

        | attributes | JSON Object | No | A dictionary containing user
        attributes to add / update in the user profile. |

        | platforms | List | No | List of dictionaries with the associated
        platforms out of ANDROID, iOS, and web an |


        **Where to find DATA API ID and API KEY?**


        *   Username(DATA API ID) and password(DATA API KEY) are available at
        ***Settings > APIs > DATA API Settings***.
            

        Do the following when you are using the API for the first-time
        authentication:


        1.  Navigate to ***Settings > APIs > DATA API Settings***.

        2.  Click Generate Key

        3.  Save the details on the Data APIs settings page. User name - DATA
        API ID Password - DATA API KEY
            

        Note - APP ID can be found in ***Settings > General .*** The APP ID is
        the usually same as DATA API ID.


        API Documentation -
        [https://developers.moengage.com/hc/en-us/articles/4413167462804-User-](https://developers.moengage.com/hc/en-us/articles/4413167462804-User-)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                type: customer
                customer_id: john@example.com
                attributes:
                  name: John
                  platforms:
                    - platform: ANDROID
                      active: 'true'
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: app_id
          in: query
          schema:
            type: string
          example: '{{APP ID}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
  /v1/event/{APP ID}:
    post:
      tags:
        - General
      summary: 2. Event API
      description: >-
        Event API allows you to track actions of a user.


        **Base URL**


        | Data Center | Replace {{OX}} with |

        | --- | --- |

        | DATA_CENTER_1 | 01 |

        | DATA_CENTER_2 | 02 |

        | DATA_CENTER_3 | 03 |


        **Request Body**


        | Key | Datatype | Required | Description |

        | --- | --- | --- | --- |

        | type | String | Yes | Identify the type of request. |

        | customer_id | String | Yes | Identifier to identify or create a user
        in MoEngage. |

        | device_id | String | No | 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. |

        | actions | List | Yes | List of events to be tracked for the user. |

        | action | String | Yes | The name of the event to be tracked. |

        | attributes | JSON Object | No | A dictionary containing event
        attributes to track with the event. |

        | platform | String | No | Used to identify the platform on which the
        event happened. Allowed values are ANDROID, iOS, web, or unknown. |

        | app_version | String | No | App Version of the app on which the event
        originated. |

        | user_time | Numeric(Epoch time in seconds) or String (ISO 8601 - ) |
        No | Local Time at which the event happened. |

        | current_time | Numeric (Epoch time in seconds) or String( ISO 8601) |
        No | UTC Time at which the event happened |

        | user_timezone_offset | Numeric | No | 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 |

          
        **Where to find DATA API ID and API KEY?**


        *   Username(DATA API ID) and password(DATA API KEY) are available at
        ***Settings > APIs > DATA API Settings***.
            

        Do the following when you are using the API for the first-time
        authentication:


        1.  Navigate to ***Settings > APIs > DATA API Settings***.

        2.  Click Generate Key

        3.  Save the details on the Data APIs settings page. User name - DATA
        API ID Password - DATA API KEY
            

        Note - APP ID can be found in ***Settings > General .*** The APP ID is
        the usually same as DATA API ID.


        API Documentation -
        [https://developers.moengage.com/hc/en-us/articles/4413174104852-Event-](https://developers.moengage.com/hc/en-us/articles/4413174104852-Event-)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                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: 1433837969
                    user_timezone_offset: 19800
                  - action: Purchase
                    attributes:
                      product: MacBook Air
                      Brand: Apple
                    platform: web
                    app_version: 1.2.3
                    current_time: 1433837969
                    user_timezone_offset: 19800
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: app_id
          in: query
          schema:
            type: string
          example: '{{APP ID}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
  /v1/transition/{APP ID}:
    post:
      tags:
        - General
      summary: 3. Bulk Import
      description: >-
        Transition API  

        This API allows you to batch multiple “user , device and event requests”
        in a single API request and send to MoEngage. You can batch requests of
        maximum 100 kB in a single API call.


        **Base URL**


        | Data Center | Replace {{OX}} with |

        | --- | --- |

        | DATA_CENTER_1 | 01 |

        | DATA_CENTER_2 | 02 |

        | DATA_CENTER_3 | 03 |


        **Request Body**


        | Key | Datatype | Required | Description |

        | --- | --- | --- | --- |

        | type | String | Yes | This is used to identify the type of request. |

        | element | List | Yes | List of data points (events, customers and
        devices) to track. |


        **Where to find DATA API ID and API KEY?**


        *   Username(DATA API ID) and password(DATA API KEY) are available at
        ***Settings > APIs > DATA API Settings***.
            

        Do the following when you are using the API for the first-time
        authentication:


        1.  Navigate to ***Settings > APIs > DATA API Settings***.

        2.  Click Generate Key

        3.  Save the details on the Data APIs settings page. User name - DATA
        API ID Password - DATA API KEY
            

        Note - APP ID can be found in ***Settings > General .*** The APP ID is
        the usually same as DATA API ID.


        API Documentation -
        [https://developers.moengage.com/hc/en-us/articles/4413174113044-Bulk-Import-](https://developers.moengage.com/hc/en-us/articles/4413174113044-Bulk-Import-)
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                type: transition
                elements:
                  - type: customer
                    customer_id: john@example.com
                    attributes:
                      name: John
                      platforms:
                        - platform: ANDROID
                          active: 'true'
                  - type: device
                    customer_id: john@example.com
                    device_id: 96bd03b6-defc-4203-83d3-dc1c73080232
                    attributes:
                      brand: Apple
                      platform: iOS
                      push_id: irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I
                  - 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
      security:
        - basicAuth: []
      parameters:
        - name: Content-Type
          in: header
          schema:
            type: string
          example: application/json
        - name: app_id
          in: query
          schema:
            type: string
          example: '{{APP ID}}'
      responses:
        '200':
          description: Successful response
          content:
            application/json: {}
