swagger: '2.0' info: title: Usage Consumption API description: 'API to fetch Airtime, Currency, Voice, Data and SMS balance details for a subscriber.' version: '1.0' host: api.mtn.com basePath: /usageConsumption/v1/ schemes: - https consumes: - application/json;charset=utf-8 produces: - application/json;charset=utf-8 securityDefinitions: ApiKeyAuth: type: "apiKey" name: "X-API-Key" in: "header" OAuth2: type: oauth2 flow: application tokenUrl: 'https://api.mtn.com/v1/oauth/access_token' security: - OAuth2: [] - ApiKeyAuth: [] tags: - name: usageConsumptionReport paths: /usageConsumptionSummary/{id}: get: operationId: retrieveUsageConsumptionSummary summary: Retrieves a usage consumption summary of a subscriber description: >- This operation is used to retrieve usage consumption summary/report of a subscriber. tags: - usageConsumptionReport parameters: - name: "transactionId" in: header required: true description: 'Client generated Id to include for tracing requests.' type: string x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc' - name: "countryCode" type: string in: header required: false description: Will be used internally by application - name: "id" required: true type: string in: path description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456" x-example: '250788123456' - name: "usageType" required: false type: string in: query description: "Type of usage concerned by the bucket, such as voice, sms, data" enum: - All - mainBalance - currencyBalance - Voice - Data - SMS - name: "senderID" required: false type: string in: query description: "Identifies the source system which integrates with MAD API" - name: "queryMode" required: false type: string in: query description: "Query mode for which the request is to be returned, pass 0 or this will be assisgned a default value(0)" - name: "x-origin-channel-id" required: false type: string in: header description: "The channel consuming the API e.g. chatbot" responses: '200': description: Success schema: $ref: '#/definitions/ResponseUsageConsumptionSummary' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Not Found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '409': description: Conflict schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /usageConsumptionDetailedReport/{id}: get: operationId: retrieveUsageConsumptionDetailedReport summary: Retrieves a usage consumption Detailed Report of a subscriber description: >- This operation is used to retrieve usage consumption Detailed report of a subscriber. tags: - usageConsumptionReport parameters: - name: "transactionId" in: header required: true description: 'Client generated Id to include for tracing requests.' type: string x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc' - name: "countryCode" type: string in: header required: false description: Will be used internally by application - name: "id" required: true type: string in: path description: "Subscriber ID/ MSISDN of a customer for which usage consumption report to be fetched. example: 250789123456" x-example: '250788123456' - name: "usageType" required: true type: string in: query description: "Type of usage concerned by the bucket, such as voice, sms, data" enum: - All - mainBalance - currencyBalance - Voice - Data - SMS - name: "senderID" required: false type: string in: query description: "Identifies the source system which integrates with MAD API" responses: '200': description: Success schema: $ref: '#/definitions/ResponseUsageConsumptionDetailedReport' '400': description: Bad Request schema: $ref: '#/definitions/Error' '401': description: Unauthorized schema: $ref: '#/definitions/Error' '403': description: Forbidden schema: $ref: '#/definitions/Error' '404': description: Not Found schema: $ref: '#/definitions/Error' '405': description: Method Not allowed schema: $ref: '#/definitions/Error' '409': description: Conflict schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' definitions: ResponseUsageConsumptionSummary: type: "object" required: - resultCode - resultDescription - transactionId - data properties: resultCode: example: "0000" type: string description: Result code. Example- '0000' resultDescription: example: "Success" type: string description: Result message. Example- 'Successfully processed' transactionId: example: "6f0bece6-7df3-4da4-af02-5e7f16e5e6fc" type: string description: Transaction id returned by the provider system. data: type: array items: $ref: '#/definitions/UsageConsumptionSummary' ResponseUsageConsumptionDetailedReport: type: "object" required: - resultCode - resultDescription - transactionId - data properties: resultCode: example: "0000" type: string description: Result code. Example- '0000' resultDescription: example: "Success" type: string description: Result message. Example- 'Successfully processed' transactionId: example: "6f0bece6-7df3-4da4-af02-5e7f16e5e6fc" type: string description: Transaction id returned by the provider system. data: type: array items: $ref: '#/definitions/UsageConsumptionDetailedReport' UsageConsumptionSummary: type: object description: >- An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). properties: id: type: string description: "Unique identifier" type: type: string description: "Type of unique identifier." description: type: string description: "Description of the entity" name: type: string description: "Name of the entity." subscriberType: type: string description: 'Type of subscriber such as Prepaid, Postpaid, Hybrid etc.' enum: - Prepaid - Postpaid - Hybrid usageType: type: string description: 'Type of usage concerned by the bucket, such as voice, sms, data' bucket: type: array items: $ref: '#/definitions/UsageVolumeProduct' description: Bucket(s) included in the offer or option subscribed. UsageConsumptionDetailedReport: type: object description: >- An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). properties: id: type: string description: "Unique identifier" type: type: string description: "Type of unique identifier." description: type: string description: "Description of the entity" name: type: string description: "Name of the entity." subscriberType: type: string description: 'Type of subscriber such as Prepaid, Postpaid, Hybrid etc.' enum: - Prepaid - Postpaid - Hybrid usageType: type: string description: 'Type of usage concerned by the bucket, such as voice, sms, data' bucket: type: array items: $ref: '#/definitions/Bucket' description: Bucket(s) included in the offer or option subscribed. Bucket: type: object description: >- An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). properties: id: type: string description: "Unique identifier" type: type: string description: "Type of unique identifier." description: type: string description: "Description of the entity" name: type: string description: "Name of the entity." remainingAmount: $ref: '#/definitions/Quantity' description: "Remaining balance of the entity" activationDate: type: string format: date description: "Activation date of the entity" expiryDate: type: string format: date description: "Expiry date of the entity" bundleDetails: type: array items: $ref: '#/definitions/EntityRef' description: Bundle(s) included in the bucket or option subscribed. offerDetails: type: array items: $ref: '#/definitions/EntityRef' description: Offer(s) included in the bundle or option subscribed. EntityRef: type: object description: >- An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). properties: id: type: string description: "Unique identifier" type: type: string description: "Type of unique identifier." description: type: string description: "Description of the entity" name: type: string description: "Name of the entity." remainingAmount: $ref: '#/definitions/Quantity' description: "Remaining balance of a bucket" activationDate: type: string format: date description: "Activation date of the bucket" expiryDate: type: string format: date description: "Expiry date of the bucket" validity: type: string description: "Validity of the entity" recurring: type: boolean default: false description: "Nature of entity, i.e., one-time or recurring." recurringDate: type: string format: date description: "Recuuring date of the entity." UsageVolumeProduct: type: object description: >- A bucket (called UsageVolumeProduct in the SID model) represents a quantity of usage, as 2 hours national calls or 50 sms for example. It could be either a quantity or an amount in a currency (i.e. It could represent a fixed number of SMS, MMS, minutes of calls, quantity of data, number of events as well as a specific amount in a given currency). It requires one or more network products from which usages will debit the bucket. properties: id: type: string description: Unique identifier of the bucket name: type: string description: Bucket name description: type: string description: "Description of the relative entity." type: type: string description: "This is the type of relative entity." bucketBalance: type: array items: $ref: '#/definitions/UsageVolumeBalance' UsageVolumeBalance: type: object description: >- The balance (called UsageVolumeBalance in the SID model) defines the remaining allowed product usage quantity in terms of volume, time, currency or events. It corresponds to the initial allowed usage quantity minus the usage consumed on the bucket. properties: initialValue: $ref: '#/definitions/Quantity' description: >- Numeric initial value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example usedValue: $ref: '#/definitions/Quantity' description: >- Numeric used value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example remainingValue: $ref: '#/definitions/Quantity' description: >- Numeric remaining value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example validFor: $ref: '#/definitions/TimePeriod' description: >- Balance period between a start date time and an end date time. For prepaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the end date of the bucket. For postpaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the next bill date. currencyId: type: string description: Currency ID example: "1185" currencyName: type: string description: "Name of the currency" example: "SSD" Quantity: type: object description: An amount in a given unit properties: amount: default: 1 type: number format: float description: Numeric value in a given unit units: type: string description: Unit TimePeriod: type: object description: >- A period of time, either as a deadline (endDateTime only) a startDateTime only, or both properties: endDateTime: type: string format: date-time description: 'End of the time period, using IETC-RFC-3339 format' startDateTime: type: string format: date-time description: >- Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end Error: type: "object" title: "Error" required: - "status" - "message" properties: timestamp: type: "string" format: "date-time" description: "Time stamp of the error" status: type: "string" description: "Status/Error code returned from the provider system" error: type: "string" description: "Status/Error description" message: type: "string" description: "More error details and corrective measures" path: type: "string" description: "the path that caused the error"