openapi: 3.1.0
info:
  title: Subex Revenue Assurance & Fraud Management API
  description: >-
    Subex provides revenue assurance and fraud management APIs for telecom operators.
    APIs enable revenue leakage detection, usage reconciliation, interconnect billing
    verification, fraud analytics, and subscriber risk scoring across voice, data,
    and digital services. Subex ROC (Revenue Operations Center) is the primary platform.
  version: "1.0"
  contact:
    name: Subex Support
    url: https://www.subex.com/contact-us/
  license:
    name: Subex License Agreement
    url: https://www.subex.com/privacy-policy/
servers:
  - url: https://api.subex.example.com/roc/v1
    description: Subex ROC API (customer-hosted or cloud deployment)

security:
  - BearerAuth: []

tags:
  - name: Analytics
    description: Risk analytics and reporting

  - name: Fraud Management
    description: Fraud detection and case management
  - name: Reconciliation
    description: CDR and billing data reconciliation
  - name: Revenue Assurance
    description: Revenue leakage detection and reconciliation
paths:
  /revenue-assurance/leakages:
    get:
      operationId: listLeakageAlerts
      summary: List revenue leakage alerts
      description: >-
        Returns detected revenue leakage alerts across all monitored service streams
        including voice, data, roaming, and digital services. Supports filtering by
        leakage type, severity, date range, and resolution status.
      tags:
        - Revenue Assurance
      parameters:
        - name: startDate
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          required: false
          schema:
            type: string
            format: date
        - name: leakageType
          in: query
          schema:
            type: string
            enum: [UNBILLED_USAGE, BILLING_ERROR, PROVISIONING_MISMATCH, TARIFF_ERROR, ROAMING_LEAKAGE, INTERCONNECT_LEAKAGE]
        - name: severity
          in: query
          schema:
            type: string
            enum: [CRITICAL, HIGH, MEDIUM, LOW]
        - name: status
          in: query
          schema:
            type: string
            enum: [OPEN, IN_PROGRESS, RESOLVED, CLOSED]
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of revenue leakage alerts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeakageAlertListResponse'
        '401':
          description: Unauthorized

  /revenue-assurance/leakages/{leakageId}:
    get:
      operationId: getLeakageAlert
      summary: Get leakage alert details
      description: Returns detailed information for a specific revenue leakage alert.
      tags:
        - Revenue Assurance
      parameters:
        - name: leakageId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Leakage alert details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeakageAlert'
        '404':
          description: Alert not found

    patch:
      operationId: updateLeakageAlert
      summary: Update leakage alert status
      description: Updates the status and resolution notes for a leakage alert.
      tags:
        - Revenue Assurance
      parameters:
        - name: leakageId
          in: path
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum: [IN_PROGRESS, RESOLVED, CLOSED]
                resolutionNotes:
                  type: string
                assignedTo:
                  type: string
      responses:
        '200':
          description: Alert updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LeakageAlert'

  /fraud/cases:
    get:
      operationId: listFraudCases
      summary: List fraud cases
      description: >-
        Returns fraud cases detected by Subex fraud analytics including SIM swap,
        bypass fraud, subscription fraud, and international revenue share fraud (IRSF).
      tags:
        - Fraud Management
      parameters:
        - name: fraudType
          in: query
          schema:
            type: string
            enum: [SIM_SWAP, BYPASS_FRAUD, SUBSCRIPTION_FRAUD, IRSF, ROAMING_FRAUD, INTERCONNECT_FRAUD, WANGIRI]
        - name: status
          in: query
          schema:
            type: string
            enum: [OPEN, UNDER_INVESTIGATION, CONFIRMED, FALSE_POSITIVE, CLOSED]
        - name: riskScore
          in: query
          description: Minimum risk score threshold (0-100)
          schema:
            type: integer
            minimum: 0
            maximum: 100
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: page
          in: query
          schema:
            type: integer
            default: 0
        - name: size
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: List of fraud cases
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FraudCaseListResponse'

  /fraud/cases/{caseId}:
    get:
      operationId: getFraudCase
      summary: Get fraud case details
      description: Returns full details for a specific fraud case including evidence and timeline.
      tags:
        - Fraud Management
      parameters:
        - name: caseId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Fraud case details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FraudCase'
        '404':
          description: Not found

  /fraud/subscribers/{msisdn}/risk-score:
    get:
      operationId: getSubscriberRiskScore
      summary: Get subscriber risk score
      description: >-
        Returns the current fraud risk score for a subscriber MSISDN based on
        behavioral analytics, call pattern analysis, and historical fraud indicators.
      tags:
        - Analytics
        - Fraud Management
      parameters:
        - name: msisdn
          in: path
          required: true
          description: Subscriber MSISDN (international format without +)
          schema:
            type: string
          example: "14155552671"
      responses:
        '200':
          description: Subscriber risk score
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SubscriberRiskScore'

  /reconciliation/runs:
    get:
      operationId: listReconciliationRuns
      summary: List reconciliation runs
      description: Returns reconciliation run history for CDR and billing data matching.
      tags:
        - Reconciliation
      parameters:
        - name: startDate
          in: query
          schema:
            type: string
            format: date
        - name: endDate
          in: query
          schema:
            type: string
            format: date
        - name: runType
          in: query
          schema:
            type: string
            enum: [VOICE_CDR, DATA_CDR, ROAMING, INTERCONNECT, BILLING]
        - name: status
          in: query
          schema:
            type: string
            enum: [RUNNING, COMPLETED, FAILED, CANCELLED]
      responses:
        '200':
          description: Reconciliation run list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReconciliationRunListResponse'

  /analytics/summary:
    get:
      operationId: getAnalyticsSummary
      summary: Get revenue assurance analytics summary
      description: >-
        Returns aggregated metrics on revenue leakage, fraud losses, and recovery
        amounts for a specified period.
      tags:
        - Analytics
      parameters:
        - name: period
          in: query
          required: true
          schema:
            type: string
            enum: [DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY]
          example: "MONTHLY"
        - name: date
          in: query
          required: true
          schema:
            type: string
            format: date
          description: Period reference date
      responses:
        '200':
          description: Analytics summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AnalyticsSummary'

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

  schemas:
    LeakageAlert:
      type: object
      properties:
        leakageId:
          type: string
        leakageType:
          type: string
          enum: [UNBILLED_USAGE, BILLING_ERROR, PROVISIONING_MISMATCH, TARIFF_ERROR, ROAMING_LEAKAGE, INTERCONNECT_LEAKAGE]
        severity:
          type: string
          enum: [CRITICAL, HIGH, MEDIUM, LOW]
        status:
          type: string
          enum: [OPEN, IN_PROGRESS, RESOLVED, CLOSED]
        detectedAt:
          type: string
          format: date-time
        serviceType:
          type: string
          enum: [VOICE, DATA, SMS, ROAMING, INTERCONNECT, DIGITAL]
        estimatedLoss:
          type: number
          description: Estimated revenue loss in USD
        currency:
          type: string
          default: USD
        description:
          type: string
        affectedRecordCount:
          type: integer
        dataSource:
          type: string
        controlName:
          type: string
        assignedTo:
          type: string
        resolvedAt:
          type: string
          format: date-time
          nullable: true
        resolutionNotes:
          type: string

    LeakageAlertListResponse:
      type: object
      properties:
        alerts:
          type: array
          items:
            $ref: '#/components/schemas/LeakageAlert'
        totalCount:
          type: integer
        totalEstimatedLoss:
          type: number
        page:
          type: integer
        pageSize:
          type: integer

    FraudCase:
      type: object
      properties:
        caseId:
          type: string
        fraudType:
          type: string
          enum: [SIM_SWAP, BYPASS_FRAUD, SUBSCRIPTION_FRAUD, IRSF, ROAMING_FRAUD, INTERCONNECT_FRAUD, WANGIRI]
        status:
          type: string
          enum: [OPEN, UNDER_INVESTIGATION, CONFIRMED, FALSE_POSITIVE, CLOSED]
        riskScore:
          type: integer
          minimum: 0
          maximum: 100
        detectedAt:
          type: string
          format: date-time
        subscriberMsisdn:
          type: string
        imsi:
          type: string
        estimatedFraudLoss:
          type: number
        currency:
          type: string
          default: USD
        indicators:
          type: array
          items:
            type: object
            properties:
              indicatorName:
                type: string
              indicatorValue:
                type: string
              weight:
                type: number
        actions:
          type: array
          items:
            type: object
            properties:
              actionType:
                type: string
                enum: [BLOCK_SUBSCRIBER, REDUCE_LIMIT, FLAG_FOR_REVIEW, NOTIFY_ANALYST]
              takenAt:
                type: string
                format: date-time
              takenBy:
                type: string

    FraudCaseListResponse:
      type: object
      properties:
        cases:
          type: array
          items:
            $ref: '#/components/schemas/FraudCase'
        totalCount:
          type: integer
        page:
          type: integer

    SubscriberRiskScore:
      type: object
      properties:
        msisdn:
          type: string
        riskScore:
          type: integer
          minimum: 0
          maximum: 100
        riskCategory:
          type: string
          enum: [VERY_LOW, LOW, MEDIUM, HIGH, VERY_HIGH]
        lastUpdated:
          type: string
          format: date-time
        contributingFactors:
          type: array
          items:
            type: object
            properties:
              factor:
                type: string
              contribution:
                type: number
        activeFraudCases:
          type: integer
        historicalFraudFlags:
          type: integer

    ReconciliationRun:
      type: object
      properties:
        runId:
          type: string
        runType:
          type: string
        startTime:
          type: string
          format: date-time
        endTime:
          type: string
          format: date-time
          nullable: true
        status:
          type: string
          enum: [RUNNING, COMPLETED, FAILED, CANCELLED]
        totalRecordsProcessed:
          type: integer
        matchedRecords:
          type: integer
        unmatchedRecords:
          type: integer
        matchRate:
          type: number
          description: Match rate as decimal (0.0-1.0)
        leakageAlerts:
          type: integer
          description: Number of leakage alerts generated

    ReconciliationRunListResponse:
      type: object
      properties:
        runs:
          type: array
          items:
            $ref: '#/components/schemas/ReconciliationRun'
        totalCount:
          type: integer

    AnalyticsSummary:
      type: object
      properties:
        period:
          type: string
        periodStart:
          type: string
          format: date
        periodEnd:
          type: string
          format: date
        totalRevenue:
          type: number
        leakageDetected:
          type: number
        leakageRecovered:
          type: number
        leakageRate:
          type: number
          description: Leakage as percentage of total revenue
        fraudLossDetected:
          type: number
        fraudLossPrevented:
          type: number
        openAlerts:
          type: integer
        resolvedAlerts:
          type: integer
        currency:
          type: string
          default: USD