openapi: 3.0.1
info:
  title: Elevate Tripwire API
  description: >
    ### Tripwire Management


    Currently provides read-only access to Tripwire-related entities like alerts
    and notifications to allow API users to automate processes linked to
    Tripwire usage monitoring and alerting


    #### Definitions


    * Tripwire alert - returns the date and time of alerts, the type of the
    alerts, and any additional details that may be useful in assessing the
    severity of the alerts

    * Tripwire notification - returns the activity that was performed when an
    alert was triggered, whether that's sending an email, SMS, or custom action
      Tripwire plan - a named tripwire plan of tripwire rules used to identify alerts and notifications
  version: '1.2'
servers:
  - url: https://rest.elevatebilling.com/v1
tags:
  - name: tripwire-alerts
    description: >-
      returns the date and time of alerts, the type of alert, threshold value
      and other details to allow analysis of the alert
  - name: tripwire-notifications
    description: >-
      the notifications that are (optionally) performed when alerts are
      triggered
  - name: tripwire-plans
    description: the tripwire plans that are used to generate the alerts
  - name: tripwire-alert-activities
    description: the tripwire alert activities
paths:
  /tripwire-plans:
    get:
      tags:
        - tripwire-plans
      summary: Get a list of Tripwire plans
      operationId: getTripwirePlans
      x-si-permissions:
        - VIEW_TRIPWIRE
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: name
          in: query
          description: Filter by name
          schema:
            $ref: '#/components/schemas/StringFilterParam'
          required: false
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TripwirePlan'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '500':
          description: Internal Server Error
          content: {}
  /tripwire-alerts:
    get:
      tags:
        - tripwire-alerts
      summary: Get a list of Tripwire alerts
      operationId: getTripwireAlerts
      x-si-permissions:
        - VIEW_TRIPWIRE
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: triggeredDate
          in: query
          description: Filter by the triggered alert date and time
          example: gt:2022-01-01T00:00:00Z
          required: true
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: planId
          in: query
          description: Filter by Tripwire plan identifier
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: analysisLevel
          in: query
          description: Filter alerts by analysis level
          required: false
          schema:
            type: string
            example: UPI_ROLLING_24HRS
        - name: thresholdQuantity
          in: query
          description: Filter alerts by the quantity threshold
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: thresholdPrice
          in: query
          description: Filter alerts by the major currency value threshold
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: thresholdCallCount
          in: query
          description: Filter alerts by the call count threshold
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: productReference
          in: query
          description: Filter alerts by product reference
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: customerId
          in: query
          description: Filter alerts by customer identifier
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: siteId
          in: query
          description: Filter alerts by site identifier
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TripwireAlert'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /tripwire-notifications:
    get:
      tags:
        - tripwire-notifications
      summary: Get a list of Tripwire notifications
      operationId: getTripwireNotifications
      x-si-permissions:
        - VIEW_TRIPWIRE
      security:
        - bearerAuth: []
      x-si-filterable: true
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/sort'
        - $ref: '#/components/parameters/fields'
        - name: created
          in: query
          description: Filter by the notification created date and time
          example: gt:2022-01-01T00:00:00Z
          required: true
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: eventStartDate
          in: query
          description: Filter by the date and time an event started
          example: gt:2022-01-01T00:00:00Z
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: eventEndDate
          in: query
          description: Filter by a single date and time an event ended
          example: lt:2022-01-01T00:00:00Z
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: action
          in: query
          description: Filter notifications by action taken
          required: false
          schema:
            type: string
            example: EMAIL_CUSTOMER_CONTACTS
        - name: productReference
          in: query
          description: >-
            Filter notifications by the product reference of the associated
            usage product inventory
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: usageProductInventoryId
          in: query
          description: Filter notifications by usage product inventory id
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: customerId
          in: query
          description: Filter notifications by customer identifier
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
        - name: siteId
          in: query
          description: Filter notifications by site identifier
          required: false
          schema:
            $ref: '#/components/schemas/StringFilterParam'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TripwireNotification'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '403':
          description: Forbidden
          content: {}
  /tripwire-alert-activities:
    get:
      tags:
        - tripwire-alert-activities
      summary: Get a page of Tripwire alert activities.
      description: >
        Retrieves a page of tripwire alert activities. Date filters must be used
        together - 

        either provide both filterFromDateTime and filterToDateTime, or none of
        them.
      operationId: getTripwireAlertActivities
      x-si-permissions:
        - VIEW_TRIPWIRE
      security:
        - bearerAuth: []
      parameters:
        - $ref: '#/components/parameters/page'
        - $ref: '#/components/parameters/pageSize'
        - name: filterAction
          in: query
          required: false
          description: Filter by tripwire notification action type
          schema:
            $ref: '#/components/schemas/NotificationType'
        - name: filterFromDateTime
          in: query
          required: false
          description: >-
            Filter tripwire alert activities from this date and time
            (inclusive).
          schema:
            type: string
            example: '2019-01-03T19:40:00'
        - name: filterToDateTime
          in: query
          required: false
          description: Filter tripwire alert activities to this date and time (exclusive).
          schema:
            type: string
            example: '2019-01-03T19:42:00'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TripwireAlertActivity'
        '400':
          description: Bad Request
          content: {}
        '401':
          description: Unauthorized
          content: {}
        '500':
          description: Internal Server Error
          content: {}
components:
  schemas:
    TripwirePlan:
      type: object
      properties:
        id:
          type: integer
          description: Plan identifier
          format: int64
          example: 1
        name:
          type: string
          description: Tripwire plan name
          example: Expensive Dialed 250 Plus
        enabled:
          description: Plan is enabled
          type: boolean
          default: true
    TripwireAlert:
      type: object
      properties:
        id:
          type: integer
          description: Alert identifier
          format: int64
          example: 1
        triggeredDate:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        planId:
          type: number
          description: Tripwire plan identifier
        planRuleName:
          type: string
          description: Tripwire plan rule description
          example: Daily calls exceeding £10.00
        analysisLevel:
          $ref: '#/components/schemas/AnalysisLevel'
        thresholdQuantity:
          type: integer
          format: int32
          description: Threshold quantity value
          example: 5
        thresholdPrice:
          type: number
          description: Threshold price in major currency (e.g. pounds/dollars/euros)
          example: 10
        thresholdCallCount:
          type: integer
          format: int32
          description: Threshold call count value
          example: 15
        ratedValueBeforeDiscount:
          type: number
          description: >-
            Rated value in major currency before applying discounts (used by
            UPI_ROLLING_24HRS)
          example: 25.25
        ratedValueAfterDiscount:
          type: number
          description: >-
            Rated value in major currency after applying discounts (used by
            OPEN_BILL_RUN & SINGLE_EVENT)
          example: 15.25
        totalCallCount:
          type: integer
          format: int32
          description: Total call count value
          example: 15
        productReference:
          type: string
          description: Product reference
        customerId:
          type: number
          description: Customer identifier
          example: 1234
        siteId:
          type: number
          description: Site identifier
          example: 1234
    TripwireNotification:
      type: object
      properties:
        id:
          type: integer
          description: Notification activity identifier
          format: int64
          example: 1
        created:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        whenActionApplied:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        planId:
          type: number
          description: Tripwire plan identifier
        planRuleName:
          type: string
          description: Tripwire plan rule description
          example: Daily calls exceeding £10.00
        eventStartDate:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        eventEndDate:
          type: string
          format: date-time
          example: '2022-01-01T00:00:00Z'
        action:
          $ref: '#/components/schemas/NotificationType'
        totalPrice:
          type: number
          description: Total price in major currency (e.g. pounds/dollars/euros)
          example: 10
        totalCallCount:
          type: integer
          format: int32
          description: Total call count value
          example: 15
        usageProductInventoryId:
          type: integer
          format: int32
          description: Usage product inventory identifier
          example: 10
        productReference:
          type: string
          description: Product reference
        customerId:
          type: number
          description: Customer identifier
          example: 1234
        siteId:
          type: number
          description: Site identifier
          example: 1234
    TripwireAlertActivity:
      type: object
      properties:
        id:
          type: integer
          description: ID of the fraud alert activity
          format: int64
          example: 1
        usageProductInventoryId:
          type: integer
          format: int64
          description: ID of the usage product inventory
          example: 10
        whenActionApplied:
          type: string
          format: date-time
          description: Timestamp when the action was applied
          example: '2022-01-01T00:00:00.000Z'
        totalPriceInMinorCurrency:
          type: number
          format: decimal
          description: Total price in pence
        totalCallCount:
          type: integer
          format: int64
          description: Total call count value
          example: 15
        createdOn:
          type: string
          format: date-time
          description: Timestamp when the fraud alert record was created
          example: '2022-01-01T00:00:00.000Z'
        tripwireStartDate:
          type: string
          format: date-time
          description: Start time of the fraudulent activity
          example: '2022-01-01T00:00:00.000Z'
        tripwireEndDate:
          type: string
          format: date-time
          description: End time of the fraudulent activity
          example: '2022-01-01T00:00:00.000Z'
        tripwireRuleId:
          type: integer
          format: int64
          description: ID of the fraud rule triggered
          example: 1
        tripwirePlanId:
          type: integer
          format: int64
          description: ID of the tripwire plan associated with the alert activity
          example: 1
        action:
          $ref: '#/components/schemas/NotificationType'
    AnalysisLevel:
      type: string
      description: >-
        Tripwire analysis level used to determine ratedValueBefore/AfterDiscount
        (see TripwireAlert object)
      enum:
        - UPI_ROLLING_24_HOUR
        - UPI_OPEN_BILL_RUN
        - SINGLE_CALL
    NotificationType:
      type: string
      description: >-
        Tripwire notification activity to be performed when a Tripwire alert is
        triggered, i.e. send an email to the client/affected customer, suspend
        the number, or other custom actions (available by contacting the Elevate
        support team)
      enum:
        - EMAIL_BILLING_CLIENT
        - SMS_BILLING_CLIENT
        - EMAIL_CUSTOMER_CONTACTS
        - SMS_CUSTOMER_CONTACTS
        - TEMPORARY_OUT_OF_SERVICE
        - OUTBOUND_CALLS_BARRED
        - CUSTOM_BC_ACTION
        - USAGE_CAP_TRIGGER_ACTION
        - NO_BC_ACTION
    PageParam:
      description: Page of results to show
      minimum: 1
      type: integer
      format: int32
      example: 1
    ResultsPerPageParam:
      description: Results to return per page
      maximum: 1000
      minimum: 1
      type: integer
      format: int32
      example: 100
    SortParam:
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      example: id,name | name:desc
      type: string
    FieldsParam:
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      example: id,name
      type: string
    StringFilterParam:
      description: >-
        Filter by this string value where value can optionally be prefixed
        (in:|like:)
      example: xyz | in:x,y | like:xyz
      type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    page:
      name: page
      in: query
      description: Page of results to show
      schema:
        $ref: '#/components/schemas/PageParam'
      required: true
    pageSize:
      name: pageSize
      description: Results to return per page
      in: query
      schema:
        $ref: '#/components/schemas/ResultsPerPageParam'
      required: true
    sort:
      name: sort
      in: query
      description: >-
        Comma-delimited list of the fields to sort by - defaults to ascending
        order, suffix :desc to change
      schema:
        $ref: '#/components/schemas/SortParam'
      required: false
    fields:
      name: fields
      in: query
      description: >-
        Comma-delimited list of the field(s) to return if only a subset is
        required
      schema:
        $ref: '#/components/schemas/FieldsParam'
      required: false
