openapi: 3.0.0
info:
  contact:
    email: developers@trackonomysystems.com
    name: Developer Support
    url: https://trackonomy.ai/contact-us/
  description: >-
    External APIs are meant for interacting with Trackonomy Platform. New
    endpoints will be added regularly. Current APIs enable the following:
      * retrieve location and environmental data for assets tracked with Trackonomy tapes.
      * activate tapes using API.
      * decode Trackonomy BLE packets
      * send various messages from third party systems for integration purposes

     Locations endpoint can be used for the latest event, Historical data endpoint reveals also older data with about 15 minute delay.
  title: Trackonomy External API
  version: 1.4.0.0
paths:
  /agent-service/v1/agent/exec/e4735852-45a4-4d73-a4b4-b13b60fc5dfe:
    post:
      description: Returns historical data.
      operationId: post-historical-data
      parameters:
        - description: Customer ID for the request
          in: header
          name: customer_id
          required: true
          schema:
            type: string
            example: c89c432b-12b7-4956-8be4-904a5e95df23
        - description: Authorized groups for access control
          in: header
          name: authorized_groups
          required: true
          schema:
            example: cb2c60c7-9b47-41af-ab05-9d3fdbff44e5
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - context
              properties:
                context:
                  type: object
                  required:
                    - customer_id
                    - authorized_groups
                    - filters
                  properties:
                    authorized_groups:
                      type: string
                      format: uuid
                      example: cb2c60c7-9b47-41af-ab05-9d3fdbff44e5
                    customer_id:
                      type: string
                      format: uuid
                      example: c89c432b-12b7-4956-8be4-904a5e95df23
                    filters:
                      type: object
                      properties:
                        customer_asset_id:
                          type: string
                          description: >-
                            customer asset identifier, connected to Trackonomy
                            tape
                          example: 999-2440 0001-0001
                        event_type:
                          type: string
                          description: >
                            location option returns data without sensor
                            readings, environment option returns both location
                            and sensor data.
                          enum:
                            - location
                            - environment
                          example: environment
                        from:
                          type: string
                          format: date-time
                          description: show events from this date, time in UTC
                          example: '2025-02-07T09:02:34Z'
                        to:
                          type: string
                          format: date-time
                          description: show events until this date, time in UTC
                          example: '2025-02-07T09:02:34Z'
                        trk_asset_id:
                          type: string
                          description: Trackonomy tape QR Code
                          example: 9E-240125-08-K1B226
                      oneOf:
                        - required:
                            - trk_asset_id
                        - required:
                            - customer_asset_id
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      events:
                        items:
                          properties:
                            battery:
                              nullable: true
                              properties:
                                charge:
                                  type: string
                                  enum:
                                    - HIGH
                                    - MED
                                    - LOW
                                  example: HIGH
                                  description: >-
                                    Indicator for battery charge level with HIGH
                                    being a fresh battery, MED being normal
                                    operating range and LOW showing a battery
                                    reaching its EOL.
                              type: object
                            customer_asset_id:
                              example: AC_NY_MN_1_1
                              type: string
                              description: >-
                                asset identifier connected to Trackonomy tape at
                                the time of association
                            event_type:
                              example: environment
                              type: string
                            lat:
                              example: 40.6635742
                              type: number
                            location:
                              example: New York, USA
                              type: string
                              description: >-
                                For in-mesh events, facility name, otherwise
                                state and country
                            location_detailed:
                              example: Bellmore
                              type: string
                              description: >-
                                For in-mesh events, facility zone name,
                                otherwise city name
                            lon:
                              example: -73.52722932
                              type: number
                            sensors:
                              description: >-
                                only those sensors, which are active on the
                                tape, will be returned
                              items:
                                properties:
                                  data:
                                    example: 20.47
                                    type: number
                                  type:
                                    enum:
                                      - ambient_temp
                                      - probe_temp
                                      - shock
                                      - humidity
                                      - pressure
                                      - light
                                    example: ambient_temp
                                    type: string
                                  units:
                                    example: C
                                    type: string
                                type: object
                              type: array
                            timestamp:
                              example: '2025-04-29T18:10:20Z'
                              format: date-time
                              type: string
                              description: event time, in UTC
                            trk_asset_id:
                              example: 9E-240125-08-K1B226
                              type: string
                              description: Trackonomy tape QR Code
                          type: object
                        type: array
                      version:
                        example: 1.2.0
                        type: string
                    type: object
                type: object
          description: Historical location and environmental data
        '400':
          content:
            application/json:
              schema:
                properties:
                  data:
                    properties:
                      message:
                        example: >-
                          Input validation error: Missing mandatory parameter:
                          customer_id
                        type: string
                      status:
                        example: error
                        type: string
                    type: object
                type: object
          description: Bad Request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Unauthorized
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Internal Server Error
      security:
        - bearerAuth: []
      summary: Request historical location and environmental data
      tags:
        - Historical data
  /locations/{asset_id}:
    get:
      operationId: get-location
      parameters:
        - description: >-
            AWB when fetching location only, for environmental data, use your
            asset id associated to Trackonomy tape.
          in: path
          name: asset_id
          required: true
          schema:
            type: string
        - description: customer_id for the request
          in: header
          name: customer_id
          required: true
          schema:
            type: string
        - description: authorized_groups for access control
          in: header
          name: authorized_groups
          required: true
          schema:
            type: string
        - description: >-
            Enable sensor readings in the response, required for non-AWB asset
            id
          in: query
          name: event
          required: false
          schema:
            enum:
              - sensor
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LocationEvent'
          description: >-
            Latest event for the specific asset, including location and
            optionally environmental data
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '500':
          $ref: '#/components/responses/500'
      security:
        - bearerAuth: []
      summary: Request the latest event with location and environmental data
      tags:
        - Locations
  /external/v1/devices/{mac_id}/decode:
    post:
      operationId: post-devices-decode
      summary: Decode single device BLE packet
      description: >-
        Decodes a BLE packet from a single device and returns sensor data
        including temperature, battery, shock events, and other telemetry
        information.
      tags:
        - Device Management
      security:
        - bearerAuth: []
      parameters:
        - name: mac_id
          in: path
          required: true
          schema:
            type: string
          description: Device MAC address
          example: Trackonomy device macid
        - name: customer_id
          in: header
          required: true
          schema:
            type: string
          description: Customer identifier
          example: Unique customer UUID
        - name: authorized_groups
          in: header
          required: true
          schema:
            type: string
          description: Authorized groups for access control
          example: Unique customer sub-group UUID
        - name: product_id
          in: header
          required: true
          schema:
            type: string
          description: Product identifier
          example: Unique Trackonomy device identifier
        - name: ble_packet
          in: header
          required: true
          schema:
            type: string
          description: BLE packet data to decode
          example: Encoded Trackonomy device data
        - name: scan_time
          in: header
          required: true
          schema:
            type: string
          description: Scan timestamp
          example: Event time
      responses:
        '200':
          description: Successfully decoded BLE packet
          content:
            application/json:
              schema:
                type: object
                properties:
                  qr_code:
                    type: string
                    example: TRK123456789
                  cts:
                    type: number
                    example: 1730813898
                  ts:
                    type: number
                    example: 1730813898
                  bat:
                    type: number
                    example: 3.2
                  temp:
                    type: number
                    example: 22.5
                  over_temp:
                    type: number
                    example: 35
                  over_temp_ts:
                    type: number
                    example: 1730813800
                  shock:
                    type: number
                    example: 2.5
                  shock_ts:
                    type: number
                    example: 1730813800
                  shock_count:
                    type: number
                    example: 3
                  fw_ver:
                    type: string
                    example: 1.2.3
        '400':
          description: Bad Request - Missing required parameters or invalid BLE packet
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Missing required headers customer_id or authorized_groups
                  code:
                    type: integer
                    example: 400
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized access
                  code:
                    type: integer
                    example: 401
        '404':
          description: Device not found or not associated with customer
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
                  code:
                    type: integer
                    example: 404
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  code:
                    type: integer
                    example: 500
  /external/v1/devices/decode:
    post:
      operationId: post-devices-decode-batch
      summary: Decode multiple device BLE packets
      description: >-
        Processes multiple BLE packets from different devices in a single
        request. Ideal for bulk operations and batch processing.
      tags:
        - Device Management
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: header
          required: true
          schema:
            type: string
          description: Customer identifier
          example: Unique customer UUID
        - name: authorized_groups
          in: header
          required: true
          schema:
            type: string
          description: Authorized groups for access control
          example: Unique customer sub-group UUID
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
                required:
                  - mac_id
                  - ble_packet
                  - product_id
                  - scan_time
                properties:
                  mac_id:
                    type: string
                    example: Trackonomy device macid
                  ble_packet:
                    type: string
                    example: Encoded Trackonomy device data
                  product_id:
                    type: string
                    example: Unique Trackonomy device identifier
                  scan_time:
                    type: string
                    example: Event time
            example:
              - mac_id: A1B2C3D4E5F6
                ble_packet: XXXXXXXX
                product_id: example-device
                scan_time: '1730813898'
              - mac_id: A1B2C3D4E5F6
                ble_packet: YYYYYYYYYYYY
                product_id: example-device
                scan_time: '1730813899'
      responses:
        '200':
          description: Successfully processed bulk decode request
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    mac_id:
                      type: string
                      example: A1B2C3D4E5F6
                    qr_code:
                      type: string
                      example: TRK123456789
                    cts:
                      type: number
                      example: 1730813898
                    ts:
                      type: number
                      example: 1730813898
                    bat:
                      type: number
                      example: 3.2
                    temp:
                      type: number
                      example: 22.5
                    error:
                      type: string
                      example: Invalid BLE packet
        '400':
          description: Bad Request - Missing required parameters or invalid request body
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Missing required headers customer_id or authorized_groups
                  code:
                    type: integer
                    example: 400
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized access
                  code:
                    type: integer
                    example: 401
        '413':
          description: Payload Too Large - Request body exceeds maximum allowed size
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Request body length greater than 250
                  code:
                    type: integer
                    example: 413
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  code:
                    type: integer
                    example: 500
  /external/messages:
    post:
      operationId: post-messages
      summary: Process external messages
      description: >-
        Processes external messages including device patches and manifest data.
        Supports different message types for various data processing needs.
      tags:
        - Messaging
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: header
          required: true
          schema:
            type: string
          description: Customer identifier
          example: Unique customer UUID
        - name: authorized_groups
          in: header
          required: true
          schema:
            type: string
          description: Authorized groups for access control
          example: Unique customer sub-group UUID
        - name: message_type
          in: header
          required: true
          schema:
            type: string
            enum:
              - DEVICE_DATA
              - MANIFEST_DATA
              - CARGOIQ
          description: Type of message to process
          example: DEVICE_DATA
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                message_type:
                  type: string
                  enum:
                    - DEVICE_DATA
                    - MANIFEST_DATA
                    - CARGOIQ
                  example: DEVICE_DATA
                data:
                  type: object
                  description: Message data payload
            examples:
              manifest_data:
                value:
                  message_type: MANIFEST_DATA
                  data:
                    asset_barcode: EXAMPLE BARCODE
                    shipped_date: 1755907016
                    shipment_id: EXAMPLE SHIPMENT ID
                    container_id: EXAMPLE CONTAINER ID
              device_data:
                value:
                  message_type: DEVICE_DATA
                  data:
                    device_id: DEVICE123
                    sensor_data:
                      temperature: 22.5
                      humidity: 45.2
                    timestamp: 1730813898
              cargoiq_data:
                value:
                  message_type: CARGOIQ
                  data:
                    bookingPublishEvent:
                      bookingDetails:
                        awb: EXAMPLE BARCODE
                        bookingReference: EXAMPLE REFERENCE
                        bookingStatus: QUE
                        taxAmount: 0
                        origin: LAX
                        destination: ATL
                        shippingDate: '2025-09-25'
                        agentCode: EXAMPLE AGENT CODE
                        agentName: EXAMPLE AGENT NAME
                        product: DSH
                        specialHandlingCodes:
                          - ABC
                          - XYZ
                        promoCode: null
                        valueAddedServices: []
                        shipmentDetails:
                          - commodity: PER
                            pieces: 10
                            weight: 100
                            adjustedWeight: 0
                            volume: 0.723
                            natureOfGoods: PERISHABLES (GENERAL)
                            handlingCode: PER
                            dimensions:
                              - pieces: 10
                                weight: 100
                                container: null
                                length: 5
                                width: 5
                                height: 5
                                tiltable: false
                                stackable: true
                            uldDetails: []
                            complementoryHandlingCodes: []
                        latestAcceptanceTime: '2025-03-23T18:00:00.000Z'
                        timeOfAvailability: null
                        flights:
                          - flightCarrier: DL
                            flightNumber: '001'
                            departureDate: '2025-03-23'
                            departureAirport: LAX
                            arrivalAirport: ATL
                            bookingStatus: BOOKED
                            pieces: 10
                            weight: 100
                            volume: 0.723
                            maindeckContainer: 0
                            maindeckPallet: 0
                            lowerdeckContainer: 0
                            lowerdeckPallet: 0
                            forceQueue: false
                            forceConfirm: null
                            queueReason: XYZ
                            allotmentIdentifier: ABC
                            remarks: ''
                            std: '2025-04-14T18:00:00.000Z'
                            sta: '2025-04-12T18:00:00.000Z'
                            aircraftType: null
                        bookingContact: null
                        shipper:
                          code: EXAMPLE CODE
                          name: EXAMPLE NAME
                          address: EXAMPLE ADDRESS
                          city: EXAMPLE CITY
                          state: EXAMPLE STATE
                          postCode: EXAMPLE ZIPCODE
                          country: EXAMPLE COUNTRY
                          telephone: EXAMPLE TELEPHONE
                          email: EXAMPLE EMAIL
                          station: null
                        consignee:
                          code: EXAMPLE CODE
                          name: EXAMPLE NAME
                          address: EXAMPLE ADDRESS
                          city: EXAMPLE CITY
                          state: EXAMPLE STATE
                          postCode: EXAMPLE ZIPCODE
                          country: EXAMPLE COUNTRY
                          telephone: EXAMPLE TELEPHONE
                          email: EXAMPLE EMAIL
                          consigneeEori: null
                          station: null
                        emergencyContact: null
                        quoteId: null
                        charges:
                          isSpotrate: false
                          allInRate: false
                          rate: null
                          airfreightCharge: 2142.2
                          chargeableWeight: null
                          tax: null
                          otherCharge: null
                          otherCharges: []
                          totalCharge: null
                          currency: SEK
                        handlingInfo: ''
                        bookingRemarks: ''
                        bookingSourceName: null
                        paymentType: PP
                        preScreened: false
                        dvForCarriage: 0
                        dvForCustoms: null
                        insuranceAmount: 0
                        serviceClass: ''
                        ratedCustomer: EXAMPLE
                        unitOfMeasure:
                          weight: LBS
                          volume: CFT
                          length: IN
                      eventMetadata:
                        id: 72cb8125-d5d1-4710-a9c6-c328aa50c20b
                        timestamp: Fri Mar 21 12:02:27 UTC 2025
                        type: BOOKING_PUBLISH
      responses:
        '201':
          description: Successfully processed the message
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Successfully processed the message
                  code:
                    type: number
                    example: 201
        '400':
          description: Bad Request - Invalid message type or payload
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Missing required headers customer_id or authorized_groups
                  code:
                    type: integer
                    example: 400
        '401':
          description: Unauthorized - Invalid or missing authentication token
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Unauthorized access
                  code:
                    type: integer
                    example: 401
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Resource not found
                  code:
                    type: integer
                    example: 404
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: Internal Server Error
                  code:
                    type: integer
                    example: 500
  /devices/v1/parcel:
    post:
      operationId: post-devices-parcel
      summary: Add device
      description: This API is used to activate a tape with its correct configuration.
      tags:
        - Device Management
      security:
        - bearerAuth: []
      parameters:
        - name: customer_id
          in: header
          required: true
          schema:
            type: string
          description: The ID of the customer.
        - name: authorized_groups
          in: header
          required: true
          schema:
            type: string
          description: The department/group authorized for this request.
        - name: facility_id
          in: header
          required: false
          schema:
            type: string
          description: The facility ID where the device is activated.
        - name: X-Correlation-Id
          in: header
          required: false
          schema:
            type: string
          description: Unique ID for tracking the request (auto-generated if not provided).
        - name: qrcode
          in: query
          required: true
          schema:
            type: string
          description: The QR code of the device.
        - name: tape_id
          in: query
          required: true
          schema:
            type: string
          description: The unique identifier of the tape (MAC address or UUID).
        - name: abc
          in: query
          required: false
          schema:
            type: string
          description: >-
            Customer's asset identifier like AWB, shipment number, asset ID etc.
            Shown later in location data.
        - name: retry
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: 'Retry flag (default: 0).'
        - name: override
          in: query
          required: false
          schema:
            type: integer
            default: 0
          description: >-
            Set to 1 to force delete and recreate the record if it exists.
            Default 0.
        - name: appId
          in: query
          required: true
          schema:
            type: string
          description: >-
            Application ID (defaults to system default if not provided) - get
            correct values from Trackonomy.
        - name: dstatus
          in: query
          required: true
          schema:
            type: integer
          description: Device status (1 for active).
        - name: abcd
          in: query
          required: false
          schema:
            type: string
          description: Asset Description.
        - name: iu
          in: query
          required: false
          schema:
            type: string
          description: Image URL.
        - name: apn
          in: query
          required: false
          schema:
            type: string
          description: APN configuration.
        - name: tt
          in: query
          required: true
          schema:
            type: string
          description: Tape Type (e.g., 'Green', 'Black').
        - name: tp
          in: query
          required: true
          schema:
            type: string
          description: Tape Personality - use "Parcel"
        - name: agps
          in: query
          required: false
          schema:
            type: string
          description: Activation GPS coordinates.
        - name: macad
          in: query
          required: false
          schema:
            type: string
          description: MAC address (explicit).
        - name: fw_version
          in: query
          required: false
          schema:
            type: string
          description: Firmware version.
        - name: tracked_application_id
          in: query
          required: false
          schema:
            type: string
          description: Tracked Application ID.
        - name: notes
          in: query
          required: false
          schema:
            type: string
          description: Additional notes.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Resource created
        '201':
          description: Created
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 200
                  message:
                    type: string
                    example: Resource created
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '404':
          $ref: '#/components/responses/404'
        '409':
          description: Conflict - Device already exists (and override was not enabled)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          $ref: '#/components/responses/500'
components:
  responses:
    '400':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Bad Request
    '401':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Unauthorized
    '404':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Resource Not Found
    '500':
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
      description: Internal Server Error
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          description: HTTP status code associated with the error
          example: 500
          type: integer
        message:
          description: Error message describing what went wrong
          example: Internal Server Error
          type: string
    Asset:
      properties:
        event_type:
          enum:
            - location
            - environment
          example: environment
          type: string
        lat:
          example: 33.6388667
          type: number
        location:
          example: ATL Warehouse
          type: string
        location_detailed:
          example: COOLER FRONTWALL
          type: string
        lon:
          example: -84.41425556
          type: number
        sensors:
          items:
            $ref: '#/components/schemas/Sensor'
          type: array
        time_zone:
          example: America/Los_Angeles
          type: string
        timestamp:
          example: '2025-02-07T09:02:34'
          type: string
        trk_asset_id:
          description: Customer asset ID associated to the Trackonomy tape
          example: 999-2440 0001-0001
          type: string
        vendor_asset_id:
          description: Trackonomy tape QR Code
          example: 06-140524-19-N1CE39
          type: string
      type: object
    LocationEvent:
      properties:
        assets:
          items:
            $ref: '#/components/schemas/Asset'
          type: array
        uuid:
          example: a51799fa-4765-4f9c-9460-2d44fc2fe27f
          type: string
        vendor_id:
          example: c59f7130-e0b7-4aff-ac6e-a97dcfbd9222
          type: string
        version:
          example: 1.0.0
          type: string
      type: object
    Sensor:
      properties:
        data:
          example: 25.5
          type: number
        type:
          enum:
            - ambient_temp
            - probe_temp
            - shock
            - humidity
            - pressure
            - light
          example: ambient_temp
          type: string
        units:
          example: ℃
          type: string
      type: object
  securitySchemes:
    bearerAuth:
      bearerFormat: JWT
      scheme: bearer
      type: http
security:
  - bearerAuth: []
servers:
  - description: PPE API for Locations data
    url: https://ppe.api.trackonomy.com/external
  - description: PPE API for Historical data
    url: https://ppe.mt.trackonomysystems.com
tags:
  - description: >-
      This API allows to request location and environmental data for assets
      tracked with Trackonomy tapes.

       *available sensor data* depends on the exact model of tape used and sensor configuration applied to the specific device. Value -255 indicates sensor unavailability. 

       *location_detailed* info can only be returned if Trackonomy indoor network is used by customer at the given location.
    name: Locations
  - description: >-
      This endpoint allows requesting historical location and environmental data
      based on provided filters. Up to 1 year of history is available, at once
      maximum 1 month or 1000 events can be fetched. If no time frame provided,
      the latest event is returned.
    name: Historical data
  - description: >-
      Services to activate new devices and decode BLE packets either one by one
      or in batch
    name: Device Management
  - description: >-
      Service to process external messages and modify device status based on the
      inputs. 

      *NB!* Usage of the given API needs prior alignment with customer as each
      received message and intended behavior is different.  Provided examples
      are some possible ways to use the endpoint.
    name: Messaging
