openapi: 3.2.0
info:
  description: This is the mParticle Event Server
  version: 1.0.0
  title: mParticle Events API
  termsOfService: http://www.mparticle.com
  contact:
    email: support@mparticle.com
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://s2s.mparticle.com/v2
  description: mParticle Events API Server
security:
- basic: []
tags:
- name: Events
  description: Send your data to the mParticle platform.
paths:
  /events:
    post:
      tags:
      - Events
      summary: Send events to mParticle
      description: ''
      operationId: uploadEvents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Batch'
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request - malformed JSON or required fields missing.
          content:
            application/json:
              examples:
                badrequest:
                  value:
                    errors:
                    - code: BAD_REQUEST
                      message: Required event field "event_type" is missing or empty.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized - authentication missing or invalid
        '403':
          description: Forbidden - API key/secret are present but not valid
        '429':
          description: Too many requests - rate limiting is being applied
        '503':
          description: Service unavailable - the message should be retried after a back off
  /bulkevents:
    post:
      tags:
      - Events
      summary: Send events to mParticle
      description: ''
      operationId: bulkUploadEvents
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkBatch'
      responses:
        '202':
          description: Accepted
        '400':
          description: Bad Request - malformed JSON or required fields missing.
          content:
            application/json:
              examples:
                badrequest:
                  value:
                    errors:
                    - code: BAD_REQUEST
                      message: Required event field "event_type" is missing or empty.
              schema:
                $ref: '#/components/schemas/ApiErrorResponse'
        '401':
          description: Unauthorized - authentication missing or invalid
        '403':
          description: Forbidden - API key/secret are present but not valid
        '429':
          description: Too many requests - rate limiting is being applied
        '503':
          description: Service unavailable - the message should be retried after a back off
components:
  schemas:
    DeviceCurrentState:
      properties:
        time_since_start_ms:
          type: integer
        battery_level:
          type: number
        data_connection_type:
          type: string
        data_connection_type_detail:
          type: string
        gps_state:
          type: boolean
        total_system_memory_usage_bytes:
          type: integer
        disk_space_free_bytes:
          type: integer
        external_disk_space_free_bytes:
          type: integer
        cpu:
          type: string
        system_memory_available_bytes:
          type: number
        system_memory_low:
          type: boolean
        system_memory_threshold_bytes:
          type: number
        application_memory_available_bytes:
          type: number
        application_memory_max_bytes:
          type: number
        application_memory_total_bytes:
          type: number
        device_orientation:
          type: string
          enum:
          - portrait
          - portrait_upside_down
          - landscape
          - LandscapeLeft
          - LandscapeRight
          - FaceUp
          - FaceDown
          - Square
        status_bar_orientation:
          type: string
          enum:
          - portrait
          - portrait_upside_down
          - landscape
          - LandscapeLeft
          - LandscapeRight
          - FaceUp
          - FaceDown
          - Square
      additionalProperties: false
    ApiErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              message:
                type: string
    EventType:
      type: string
      enum:
      - session_start
      - session_end
      - screen_view
      - custom_event
      - crash_report
      - opt_out
      - first_run
      - pre_attribution
      - push_registration
      - application_state_transition
      - push_message
      - network_performance
      - breadcrumb
      - profile
      - push_reaction
      - commerce_event
      - user_attribute_change
      - user_identity_change
      - uninstall
    DeviceInformation:
      properties:
        brand:
          type: string
        product:
          type: string
        device:
          type: string
        android_uuid:
          type: string
        device_manufacturer:
          type: string
        platform:
          type: string
          enum:
          - iOS
          - Android
          - web
          - desktop
          - tvOS
          - roku
          - out_of_band
          - smart_tv
          - xbox
        os_version:
          type: string
        device_model:
          type: string
        screen_height:
          type: integer
        screen_width:
          type: integer
        screen_dpi:
          type: integer
        device_country:
          type: string
        locale_language:
          type: string
        locale_country:
          type: string
        network_country:
          type: string
        network_carrier:
          type: string
        network_code:
          type: string
        network_mobile_country_code:
          type: string
        timezone_offset:
          type: integer
        build_identifier:
          type: string
        http_header_user_agent:
          type: string
        ios_advertising_id:
          type: string
        att_authorization_status:
          type: string
          enum:
          - authorized
          - denied
          - not_determined
          - restricted
        att_timestamp_unixtime_ms:
          type: number
        push_token:
          type: string
        cpu_architecture:
          type: string
        is_tablet:
          type: boolean
        push_notification_sound_enabled:
          type: boolean
        push_notification_vibrate_enabled:
          type: boolean
        radio_access_technology:
          type: string
        supports_telephony:
          type: boolean
        has_nfc:
          type: boolean
        bluetooth_enabled:
          type: boolean
        bluetooth_version:
          type: string
        ios_idfv:
          type: string
        android_advertising_id:
          type: string
        build_version_release:
          type: string
        limit_ad_tracking:
          type: boolean
        amp_id:
          type: string
        is_dst:
          type: boolean
        roku_advertising_id:
          type: string
        roku_publisher_id:
          type: string
        microsoft_advertising_id:
          type: string
        microsoft_publisher_id:
          type: string
        fire_advertising_id:
          type: string
      additionalProperties: false
    SourceInformation:
      readOnly: true
      properties:
        channel:
          type: string
          enum:
          - native
          - javascript
          - pixel
          - desktop
          - partner
          - server_to_server
        partner:
          type: string
        replay_request_id:
          type: string
        replay_job_id:
          type: string
        is_historical:
          type: boolean
      additionalProperties: false
    ConsentState:
      properties:
        gdpr:
          $ref: '#/components/schemas/GDPRConsentState'
      required:
      - gdpr
      additionalProperties: false
    ApplicationInformation:
      properties:
        application_name:
          type: string
        application_version:
          type: string
        application_build_number:
          type: string
        install_referrer:
          type: string
        package:
          type: string
        os:
          type: string
          default: Unknown
          enum:
          - Unknown
          - IOS
          - Android
          - WindowsPhone
          - MobileWeb
          - UnityIOS
          - UnityAndroid
          - Desktop
          - TVOS
          - Roku
          - OutOfBand
          - Alexa
          - SmartTV
          - FireTV
          - Xbox
        apple_search_ads_attributes:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
      additionalProperties: false
    Batch:
      properties:
        source_request_id:
          type: string
        batch_context:
          $ref: '#/components/schemas/BatchContext'
        events:
          type: array
          description: Provide a list of event objects - such as CustomEvent, ScreenViewEvent, or CommerceEvent
          items:
            $ref: '#/components/schemas/BaseEvent'
        device_info:
          $ref: '#/components/schemas/DeviceInformation'
        application_info:
          $ref: '#/components/schemas/ApplicationInformation'
        user_attributes:
          type: object
          additionalProperties:
            type: object
        deleted_user_attributes:
          type: array
          items:
            type: string
        user_identities:
          type: object
          properties:
            other:
              type: string
            customer_id:
              type: string
            facebook:
              type: string
            twitter:
              type: string
            google:
              type: string
            microsoft:
              type: string
            yahoo:
              type: string
            email:
              type: string
            alias:
              type: string
            facebook_custom_audience_id:
              type: string
            other_id_2:
              type: string
            other_id_3:
              type: string
            other_id_4:
              type: string
            other_id_5:
              type: string
            other_id_6:
              type: string
            other_id_7:
              type: string
            other_id_8:
              type: string
            other_id_9:
              type: string
            other_id_10:
              type: string
            mobile_number:
              type: string
            phone_number_2:
              type: string
            phone_number_3:
              type: string
          additionalProperties: false
        environment:
          type: string
          default: production
          enum:
          - unknown
          - development
          - production
        api_key:
          type: string
        api_keys:
          type: array
          items:
            type: string
        ip:
          type: string
        integration_attributes:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: string
        partner_identity:
          type: string
        source_info:
          $ref: '#/components/schemas/SourceInformation'
        mp_deviceid:
          type: string
        attribution_info:
          $ref: '#/components/schemas/AttributionInfo'
        timestamp_unixtime_ms:
          type: integer
          format: int64
        batch_id:
          type: integer
          format: int64
        mpid:
          type: integer
          format: int64
        sdk_version:
          type: string
        consent_state:
          $ref: '#/components/schemas/ConsentState'
        job_id:
          type: string
      additionalProperties: false
      required:
      - environment
    CommonEventData:
      properties:
        timestamp_unixtime_ms:
          type: integer
        event_id:
          type: integer
          format: int64
          readOnly: true
        source_message_id:
          type: string
        session_id:
          type: integer
          format: int64
        session_uuid:
          type: string
        session_start_unixtime_ms:
          type: integer
        event_start_unixtime_ms:
          type: integer
        custom_attributes:
          type: object
          additionalProperties:
            type: string
        location:
          $ref: '#/components/schemas/GeoLocation'
        device_current_state:
          $ref: '#/components/schemas/DeviceCurrentState'
        is_goal_defined:
          type: boolean
        lifetime_value_change:
          type: boolean
        lifetime_value_attribute_name:
          type: string
        data_connection_type:
          type: string
        event_num:
          type: integer
        view_controller:
          type: string
        is_main_thread:
          type: boolean
        canonical_name:
          type: string
        event_system_notification_info:
          $ref: '#/components/schemas/EventSystemNotificationInfo'
    GeoLocation:
      properties:
        latitude:
          type: number
        longitude:
          type: number
        accuracy:
          type: number
      required:
      - latitude
      - longitude
      additionalProperties: false
    BaseEvent:
      properties:
        data:
          $ref: '#/components/schemas/CommonEventData'
        event_type:
          $ref: '#/components/schemas/EventType'
    EventSystemNotificationInfo:
      readOnly: true
      properties:
        type:
          type: string
          enum:
          - gdpr_change
      required:
      - type
    BulkBatch:
      type: array
      items:
        $ref: '#/components/schemas/Batch'
    GDPRConsentState:
      properties:
        regulation:
          type: string
        document:
          type: string
        consented:
          type: boolean
        timestamp_unixtime_ms:
          type: integer
        location:
          type: string
        hardware_id:
          type: string
      required:
      - regulation
      - document
      - consented
      - timestamp_unixtime_ms
      - location
      - hardware_id
      additionalProperties: false
    DataPlanContext:
      properties:
        plan_id:
          type: string
        plan_version:
          type: integer
      required:
      - plan_id
    BatchContext:
      properties:
        data_plan:
          $ref: '#/components/schemas/DataPlanContext'
    AttributionInfo:
      properties:
        service_provider:
          type: string
        publisher:
          type: string
        campaign:
          type: string
      required:
      - service_provider
      - publisher
      - campaign
      additionalProperties: false