Moloco Commerce Media Event API

openapi: 3.0.0
info:
  title: Event API
  version: '1.0'
  contact:
    name: Moloco Inc.
    url: https://www.molocoads.com
tags:
- name: RmpEventApi
  description: UserEvent is a service to collect external user events.
paths:
  /rmp/event/v1/platforms/{platform}/userevents:
    post:
      summary: PostUserEvent
      description: Post an individual user event. Server host may vary by platform. Moloco's account manager will provide
        accurate host information.
      operationId: RmpEventApi_PostUserEvent
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1PostUserEventResponse'
        '400':
          description: Bad request. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '401':
          description: Unauthorized. The request does not have valid authentication credentials for the operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '403':
          description: Permission denied. The caller does not have permission to execute the specified operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '404':
          description: Not found. One or more resources required to perform the request does not exist. Detailed cause can
            be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '429':
          description: Too many requests either by platform or by user. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
        '500':
          description: Internal server error. Detailed cause can be found in the response message.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/rpcStatus'
      parameters:
      - name: platform
        description: Platform for the user event.
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1Event'
        required: true
      tags:
      - Event
security:
- ApiKeyAuth: []
x-readme:
  explorer-enabled: true
servers:
- url: https://sandbox-evt.mcm-api.moloco.com
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: x-api-key
      in: header
  schemas:
    EventDevice:
      type: object
      properties:
        os:
          type: string
          description: OS of the device. "ios" or "android" must be included for the App channel type.
        os_version:
          type: string
          description: Device OS version, which is taken from the device without manipulation or normalization. (e.g., "14.4.1")
        advertising_id:
          type: string
          description: 'Deprecated. For app traffic, IDFA of iOS or ADID of android should be filled in this field. (e.g.,
            7acefbed-d1f6-4e4e-aa26-74e93dd017e4). Note that "00000000-0000-0000-0000-000000000000" is not allowed (reference:
            https://developer.apple.com/documentation/adsupport/asidentifiermanager/advertisingidentifier#discussion).'
        unique_device_id:
          type: string
          description: Deprecated. Please use persistent_id as alternative. For app traffic, a unique identifier for the device
            being used should be provided in this field. Clients can issue identifiers for their user devices or use their
            IDFV values if using iOS apps. The length of this id should not exceed 128 characters.
          maxLength: 128
        persistent_id:
          type: string
          description: 'Alternative ID to track users regardless of sign-in status. This can typically be an ID associated
            with the device that the user is on, and is highly recommended to be hashed prior to being sent to Moloco. Please
            provide this value in addition to the user_id whenever available to achieve optimal performance. If the value
            is unknown for any reason, please leave empty and do not fill in a default or random value. For further information,
            please refer to this guide: https://mcm-docs.moloco.com/docs/generating-persistent-identifiers'
          maxLength: 128
        model:
          type: string
          description: Device model, which is taken from the device without manipulation or normalization. (e.g., "iPhone
            11 Pro")
        ua:
          type: string
          description: User Agent. (e.g., "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4_2 like Mac OS X) AppleWebKit/605.1.15 (KHTML,
            like Gecko) Mobile/111FFF")
        language:
          type: string
          description: ISO-639-1 alpha-2 language code. (e.g., "en")
      additionalProperties: true
    EventEventType:
      type: string
      enum:
      - UNKNOWN_EVENT_TYPE
      - SEARCH
      - ITEM_PAGE_VIEW
      - ADD_TO_CART
      - PURCHASE
      - ADD_TO_WISHLIST
      - HOME
      - LAND
      - PAGE_VIEW
      default: UNKNOWN_EVENT_TYPE
      description: Supported EventTypes.
    EventItem:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the Item.
        price:
          $ref: '#/components/schemas/commonMoney'
        quantity:
          type: integer
          format: int32
          description: Quantity of the item. Recommended.
        item_group_id:
          type: string
          description: Unique identifier of the Item Group. id and/or item_group_id must be provided.
        seller_id:
          type: string
          description: Unique identifier of the seller of the item. This field is required for MSPI integration unless the
            seller cannot be associated with that item for the specific event.
        price_seller:
          $ref: '#/components/schemas/commonMoney'
      description: Item object
      required:
      - id
      additionalProperties: true
    commonChannelType:
      type: string
      enum:
      - UNKNOWN_CHANNEL_TYPE
      - APP
      - SITE
      - DESKTOP_SITE
      - MOBILE_SITE
      default: UNKNOWN_CHANNEL_TYPE
      description: "ChannelType enumerates available channel types. Simply using APP and SITE is fine, but you can also further\
        \ distinguish DESKTOP_SITE and MOBILE_SITE for web users.\n\n - APP: Mobile App (iOS or Android)\n - SITE: Site (e.g.\
        \ Website)\n - DESKTOP_SITE: Desktop Site (e.g. Desktop Website)\n - MOBILE_SITE: Mobile Site (e.g. Mobile Website)"
    commonCurrency:
      type: string
      enum:
      - UNKNOWN_CURRENCY
      - USD
      - KRW
      - JPY
      - EUR
      - GBP
      - SEK
      - INR
      - THB
      - IDR
      - CNY
      - CAD
      - RUB
      - BRL
      - SGD
      - HKD
      - AUD
      - PLN
      - DKK
      - VND
      - MYR
      - PHP
      - TRY
      - VES
      - AED
      - CHF
      default: UNKNOWN_CURRENCY
      description: "Currency enumerates available currencies.\n\n - UNKNOWN_CURRENCY: Unknown currency.\n - USD: US Dollar.\n\
        \ - KRW: Korean Won.\n - JPY: Japanese Yen.\n - EUR: EU Euro.\n - GBP: British Pound.\n - SEK: Swedish Krona.\n -\
        \ INR: India Rupee.\n - THB: Thailand Baht.\n - IDR: Indonesia Rupiah.\n - CNY: China Yuan.\n - CAD: Canada Dollar.\n\
        \ - RUB: Russia Ruble.\n - BRL: Brazil Real.\n - SGD: Singapore Dollar.\n - HKD: Hong Kong Dollar.\n - AUD: Autrailia\
        \ Dollar.\n - PLN: Poland Zloty.\n - DKK: Denmark Krone.\n - VND: Viet Nam Dong.\n - MYR: Malaysia Ringgit.\n - PHP:\
        \ Philippines Peso.\n - TRY: Turkey Lira.\n - VES: Venezuela Bolívar Soberano.\n - AED: United Arab Emirates Dirham.\n\
        \ - CHF: Swiss Franc."
    commonMoney:
      type: object
      properties:
        currency:
          $ref: '#/components/schemas/commonCurrency'
        amount:
          type: number
          format: double
          description: Amount of money. (e.g., 12.34)
      description: "A monetary amount in a specific currency.\nFor example, `{currency: \"USD\", amount: 12.34}` means $12.34.\
        \ \nPrice of the single item."
      required:
      - currency
      - amount
      additionalProperties: true
    commonPersonalizationMode:
      type: string
      enum:
      - UNKNOWN_PERSONALIZATION_MODE
      - STANDARD
      - METRIC_ONLY
      - ID_LESS
      default: UNKNOWN_PERSONALIZATION_MODE
      description: "PersonalizationMode determines how user identification is handled in decision and event processing.\n\n\
        \ - STANDARD: STANDARD means standard user processing with full user identification.\n - METRIC_ONLY: METRIC_ONLY\
        \ means user data is used for metric collection only, not for personalization.\n - ID_LESS: ID_LESS means no user\
        \ identification is used."
    protobufAny:
      type: object
      properties:
        '@type':
          type: string
      additionalProperties: {}
    rpcStatus:
      type: object
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/protobufAny'
      additionalProperties: true
    v1Event:
      type: object
      properties:
        id:
          type: string
          description: Recommended. Unique ID generated by the client that could be used as an identifier. The length should
            not exceed 128 characters.
          maxLength: 128
        event_type:
          $ref: '#/components/schemas/EventEventType'
        timestamp:
          type: string
          format: int64
          description: Unix timestamp in milliseconds that the event happened at. (e.g., 1617870506121)
        channel_type:
          $ref: '#/components/schemas/commonChannelType'
        domain:
          type: string
          description: Set domain to a value that can identify the domain portion of your website's URL. We recommend you
            keep the same value across your website and application if they share your backend.
        user_id:
          type: string
          description: User identifier used by the platform. This should typically be the sign-in ID used within the platform,
            and is highly recommended to be hashed prior to being sent to Moloco. Please provide this value whenever available
            to achieve optimal performance. If the value is unknown for any reason, please leave empty and do not fill in
            a default or random value.
          maxLength: 128
        device:
          $ref: '#/components/schemas/EventDevice'
        items:
          type: array
          items:
            $ref: '#/components/schemas/EventItem'
          description: Items information related to the event. Required for ADD_TO_CART, ADD_TO_WISHLIST, ITEM_PAGE_VIEW and
            PURCHASE event types.
        revenue:
          $ref: '#/components/schemas/commonMoney'
        search_query:
          type: string
          description: Query string for the search. Required for SEARCH event.
        session_id:
          type: string
          description: Deprecated. Please use custom_id as alternative. Identifier for tracking users regardless of sign-in
            status. The length should not exceed 128 characters.
          maxLength: 128
        custom_id:
          type: string
          description: Alternative ID to track users regardless of sign-in status or device. This ID should be provided as
            a third option following the user_id and device.persistent_id, and is highly recommended to be hashed prior to
            being sent to Moloco. This ID must be provided if both the user_id and device.persistent_id fields are left empty.
            Please do not fill in a default value, and instead randomize it if you must, but we recommend you send some ID
            that can be used to track users even if for a short time span. Please reach out to Moloco if you have further
            questions about this ID.
          maxLength: 128
        page_id:
          type: string
          description: "Page ID should be a uniquely assigned value for each page in the app or web site. \nIt is a mandatory\
            \ field if the Event type is PAGE_VIEW. Otherwise, it's not required to have a value for the page_id parameter.\
            \ If the Event type is PAGE_VIEW, provide a string that can identify a context of the event, such as \"electronics\"\
            , \"categories/12312\", \"azd911d\" or \"/classes/foo/lectures/bar.\" Any value will be acceptable if it helps\
            \ identify unique pages."
        referrer_page_id:
          type: string
          description: Similar to referer in HTTP, this value indicates from which page the user came to the current page.
        shipping_charge:
          $ref: '#/components/schemas/commonMoney'
        decision_track_id:
          type: string
          description: Track ID for the event. Track ID is generated by a call to the Decision API. Fill in this field accordingly
            if the user event is to be associated with a Decision API response.
        personalization_mode:
          $ref: '#/components/schemas/commonPersonalizationMode'
      description: Request body for Event API
      required:
      - event_type
      - timestamp
      - channel_type
      additionalProperties: true
    v1PostUserEventResponse:
      type: object
      additionalProperties: true