--- swagger: "2.0" info: description: |- The Data Share API facilitates data share between Data Share Agent(Data Sender) and Customer(Data Receiver) also provides a data analytics. It also provides functionality to manage provider and consumer msisdns that are linked as part of the Internet Share Bundles Product **26-August-21: ChangeID: 0000000327** - Added a new GET endpoint /customers/{customerId}/summary **20-Sept-21: ChangeID: 0000000000** - Added a new GET endpoint /providers/{providerMsisdn}/eligibility **04-Oct-21: ChangeID: 0000000000** - Modified the POST endpoint to support Addition of a Consumer to a Family Pack Shared Account **18-Oct-21: ChangeID: 0000000000** - Modified the DELETE endpoint to support delete of all connsumers, delete a specific consumer from a shared family pack **20-Nov-21: ChangeID: 0000000000** - Added a new PATCH endpoint to enable setting of consumer data limits on a shared data package version: "1.7.1" title: Customer Data Share API host: api.mtn.com basePath: "/v1/datashare" schemes: - https consumes: - application/json produces: - application/json securityDefinitions: ApiKeyAuth: type: "apiKey" name: "X-API-Key" in: "header" security: - ApiKeyAuth: [] paths: /providers/{providerMsisdn}: post: tags: - Provider summary: Add consumer msidsn to share data description: Allows a provider to add a customer to use their internet share bundle parameters: - name: "providerMsisdn" in: path description: Provider Msisdn.The format must be E.123 required: true type: string - name: transactionId type: string description: This is the transaction Id from the caller. in: header - in: body name: providerbody description: Request body required: true schema: $ref: '#/definitions/ConsumerInformation' responses: "200": description: Success schema: $ref: '#/definitions/ProviderShareResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' delete: tags: - Provider summary: Deactivates Internet sharing for a provider/consumer msisdn or removes consumer msisdns from the provider msisdn description: Allows a provider to leave data sharing or to remove a customer and hence stop them from using their internet share bundle parameters: - name: "providerMsisdn" in: path description: Provider Msisdn. This is the msisdn that has the active Internet Share Bundle. The format must be E.123 required: true type: string - name: consumerMsisdn in: query description: The msisdn that is to be stopped from using the Internet Share bundle on the provider msisdn. The format must be E.123. Use this if you'd like to remove only one consumer from sharing the provider internet share bundle required: false type: string - name: removeConsumers in: query description: set this variable to the keyword ALL if you would like to remove all consumers sharing the provider internet share bundle required: false type: string enum: - ALL - name: transactionId type: string description: This is the transaction Id from the caller. in: header - name: nodeId type: string description: This is the partner's identifier. For CIS this will be the iname in: query - name: input type: string description: This is additional input from the 3pp. For CIS, this is the product code in: query - name: targetSystem type: string in: query enum: [CIS] responses: "200": description: Success schema: $ref: '#/definitions/SuccessResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' patch: tags: - Provider summary: Update datashare limits and Suspend/Unsuspend number description: Allows a provider to adjust consumer limits parameters: - name: "providerMsisdn" in: path description: Provider Msisdn.The format must be E.123 required: true type: string - name: transactionId type: string description: This is the transaction Id from the caller. in: header - in: body name: providerbody description: Request body required: true schema: $ref: '#/definitions/ConsumerInformation' responses: "200": description: Success schema: $ref: '#/definitions/ProviderShareResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' /providers/{providerMsisdn}/activate: post: tags: - Provider summary: Activate data sharing plan description: Allows a provider to activate data sharing bundle parameters: - name: "providerMsisdn" in: path description: Provider Msisdn.The format must be E.123 required: true type: string - name: transactionId type: string description: This is the transaction Id from the caller. in: header - in: body name: providerbody description: Request body required: true schema: $ref: '#/definitions/ConsumerInformation' responses: "200": description: Success schema: $ref: '#/definitions/ProviderShareResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' get: tags: - Provider summary: Retrieve all consumer MSISDNs linked to the provider msisdn description: Provides the ability to retrieve all consumers that are sharing the internet share bundle with the provider parameters: - name: "providerMsisdn" in: path description: Provider Msisdn. The format must be E.123 required: true type: string - in: query name: clientTransactionId type: string description: 3pp transaction Id - name: partnerId in: query type: string description: This is the iname value of the partner - name: action in: query type: string description: This is the expected backend action. VIEW_FAMILY_PACK_CONSUMERS when viewing consumers and VIEW_FAMILY_PACK_PROVIDER when viewing providers enum: [VIEW_FAMILY_PACK_CONSUMERS, VIEW_FAMILY_PACK_PROVIDER] - name: viewType in: query type: string enum: [PROVIDER, CONSUMER] - in: query name: productId type: string responses: "200": description: Success schema: $ref: '#/definitions/ConsumersListResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' /providers/{providerMsisdn}/eligibility: get: tags: - Provider summary: Check if a number is a provider description: Allows a 3pp to check if a number is a provider or not parameters: - name: "providerMsisdn" in: path description: Provider Msisdn.The format must be E.123 required: true type: string - in: query name: clientTransactionId type: string description: 3pp transaction Id - name: partnerId in: query type: string description: This is the iname value of the partner - name: action in: query type: string enum: [IS_PROVIDER] - in: query name: productId type: string responses: "200": description: Success schema: $ref: '#/definitions/ProviderEligibilityResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{senderMsisdn}: post: tags: - Customer summary: Share Data description: Provides the ability to share data with customer. parameters: - name: "senderMsisdn" in: path description: Source Msisdn. The format must be E.123 required: true type: string - name: productcode type: string in: query required: true description: The product code e.g NACT_NG_others_1 - in: body name: body description: Request body required: true schema: $ref: '#/definitions/ReceiverInformation' responses: "200": description: Success schema: $ref: '#/definitions/DataShareResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' get: deprecated: true tags: - Customer summary: Retrieve Receivers' MSISDN description: Provides the ability to retrieve all registered receiver's msisdn. parameters: - name: "senderMsisdn" in: path description: Source Msisdn. The format must be E.123 required: true type: string responses: "200": description: Success schema: $ref: '#/definitions/DataShareListResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' patch: deprecated: true tags: - Customer summary: Update Receiver's information description: Provides the ability to update the receiver's msisdn and sharable data amount. parameters: - name: "senderMsisdn" in: path description: Source Msisdn. The format must be E.123 required: true type: string - in: body name: body description: Request body required: true schema: $ref: '#/definitions/ReceiverInformation' responses: "200": description: Success schema: $ref: '#/definitions/SuccessResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' delete: deprecated: true tags: - Customer summary: Remove Receiver's Msisdn description: Provides the ability for removing receiver's msisdn. parameters: - name: "senderMsisdn" in: path description: Source Msisdn. The format must be E.123 required: true type: string - name: receiverMsisdn in: query type: string description: The beneficiary msisdn. The format must be E.123 responses: "200": description: Success schema: $ref: '#/definitions/SuccessResponse' "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/analytics: get: tags: - Customer summary: Get analytic information of your data usage description: Get analytic information of your data usage and list of beneficiaries enjoying from the data. parameters: - name: "customerId" in: path description: Customer Msisdn. E.123 e.g 2349062058464 required: true type: string - name: "type" required: true type: string in: "query" enum: - provider - beneficiary description: "Select the type of query to get" - name: "startDate" in: query type: string description: "Filter the response data by start date" required: true x-example: 20201001 - name: "endDate" in: query type: string description: "Filter the response data by end date" required: true x-example: 20201004 - name: "pageNum" in: query type: string description: "Filter the response data by page number" required: false x-example: 1 - name: "pageSize" in: query type: string description: "Filter the response data by page size" required: false x-example: 5 responses: "200": description: Success schema: type: object properties: statusCode: type: string description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'" statusMessage: type: string description: "Status Message" transactionId: type: string description: "API generated Id to include for tracing requests" data: type: array items: $ref: "#/definitions/DataUsagerInformation" _links: type: object properties: self: type: string example: "https://api.mtn.com/v1/customers/23464618463/analytics" "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/summary: get: tags: - Customer summary: Get GDS summary your data usage description: Get group data share summary for your dta usage. parameters: - name: "customerId" in: path description: Customer Msisdn. E.123 e.g 2349062058464 required: true type: string - name: "type" required: true type: string in: "query" enum: - provider - beneficiary - consumer description: "Select the type of query to get" - name: "startDate" in: query type: string description: "Filter the response data by start date" required: true x-example: 20201001 - name: "endDate" in: query type: string description: "Filter the response data by end date" required: true x-example: 20201004 - name: "pageNum" in: query type: string description: "Filter the response data by page number" required: false x-example: 1 - name: "pageSize" in: query type: string description: "Filter the response data by page size" required: false x-example: 5 - name: "summaryPeriod" in: query type: string description: "Shall be mandatory for provider and beneficiary type" required: false enum: - Daily - Weekly - Monthly responses: "200": description: Success schema: type: object properties: statusCode: type: string description: "This is the MADAPI Canonical response Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system response are mapped to specific canonical response codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes'" statusMessage: type: string description: "Status Message" transactionId: type: string description: "API generated Id to include for tracing requests" customerId: type: string description: "Customer Id" data: type: object properties: pageNumber: type: number description: Current Page Number example: 1 recordsCount: type: number description: This is the number of records returned from the summary example: 25 maximumRecords: type: number description: This is the maximum number of records that can be returned summaryDetails: type: array items: $ref: "#/definitions/DataSummaryInformation" _links: type: object properties: self: type: string example: "https://api.mtn.com/v1/customers/23464618463/analytics" "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 No Allowed schema: $ref: '#/definitions/Error' "406": description: Not acceptable schema: $ref: '#/definitions/Error' "415": description: Unsupported media Type schema: $ref: '#/definitions/Error' "500": description: Internal Server Error schema: $ref: '#/definitions/Error' definitions: DataSummaryInformation: type: object description: Sumary information for the subscriber properties: id: type: string description: "Mobile number wose summary is being returned" summaryType: type: string description: Summary Type dataUsage: type: object properties: value: type: number description: Data value unit: type: string description: data unit forexample KB date: type: string week: type: string month: type: string yearMonth : type: string DataUsagerInformation: type: object description: "The impacted system success response" properties: serviceDurationUnit: type: string example: "B" servedmsisdn: type: string example: "9062292938" description: "Customer Msisdn." providerMsisdn: type: string example: "9062756289" description: "Data Provider Msisdn" serviceDuration: type: integer example: 130528 serviceClassId: type: string example: "300" serviceType: type: string example: "GPRS" currencyCode: type: string example: "NGN" dateKey: type: integer example: 20201001 apn: type: string example: "web.gprs.mtnnigeria.net" SuccessResponse: type: object properties: statusCode: type: string description: HTTP Error code extension example: "0000" errorCode: type: string description: HTTP Error code extension example: "S1001" statusMessage: type: string example: "Action Successful" transactionId: type: string description: Transaction Id used for tracking purposes example: "txn123" data: type: object properties: countryCode: type: string description: ISO Country Code example: NG action: type: string product: type: object properties: productId: type: string description: Product Id productName: type: string description: Product name productType: type: string description: Product type amountCharged: type: number format: float description: Amount charged during the delete operation notification: type: string _link: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/customers/2348064816493/dataShare" ConsumerInformation: type: object required: - customerId properties: consumerMsisdn: type: string example: "256789999781" description: The msisdn that is allowed to/stopped from using the Internet Share bundle on the provider msisdn. The format must be E.123 threshold: type: string unit: type: string nodeId: type: string description: This is the partner's identifier. For CIS this will be the iname input: type: string paymentOption: type: string targetSystem: type: string description: Backend system expected to process the service request enum: - CIS operationType: type: string description: Describes the type of operation being made in the request enum: - MAKE_UNLIMITED_ALL - ADD_MOBILE_NUMBER - SET_LIMIT_ALL - MAKE_UNLIMITED_SINGLE - SET_LIMIT_SINGLE - ACTIVATE_DATA_PLAN - SUSPEND_NUMBER - UNSUSPEND_NUMBER ReceiverInformation: type: object required: - receiverMsisdn - requestedDataAmount properties: receiverMsisdn: type: string example: "2345957585859" description: The beneficiary msisdn. The format must be E.123 requestedDataAmount: type: string example: "100" description: Total amount of data to be shared with the customer in MBs senderId: type: string example: "MyApp" description: A 3PP sender id to be forwarded to the backend DataShareResponseData: type: object description: "The impacted system success response" required: - productName properties: productName: type: string example: "Share 100MB" notification: type: string example: "You have successfully transferred 100MB Data to 2349062058463." ProviderEligibilityResponse: type: object properties: statusCode: type: string description: HTTP status codes example: "0000" statusMessage: type: string example: "Success" transactionId: type: string description: "Client generated Id to include for tracing requests." example: "12376892" data: type: object properties: eligibilityStatus: type: boolean description: This will be true if the provided number is a provider and will be false if its not a provider countryCode: type: string description: This is the mobile number for the mobile number requestId: type: string description: Request Id from the back end system ProviderShareResponse: type: object properties: statusCode: type: string description: HTTP status codes example: "0000" errorCode: type: string description: HTTP error codes example: "S1001" statusMessage: type: string example: "Success" transactionId: type: string description: "Client generated Id to include for tracing requests." example: "12376892" data: $ref: '#/definitions/ProviderPostResponseData' ProviderPostResponseData: type: object properties: notification: type: string amount: type: number requestId: type: string responseType: type: string action: type: string countryCode: type: string product: $ref: '#/definitions/ProductDetails' ProductDetails: type: object properties: productId: type: string description: Product Id productName: type: string description: Name of the product productType: type: string description: Type of the product DataShareResponse: type: object properties: statusCode: type: string description: HTTP Error code extension example: "0000" statusMessage: type: string example: "Success" transactionId: type: string description: "Client generated Id to include for tracing requests." sequenceNo: type: string description: "A uniquely generated id for tracking req/res internally on madapi" data: $ref: '#/definitions/DataShareResponseData' _link: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/customers/2348064816493/dataShare" DataShareListResponse: type: object properties: statusCode: type: string description: HTTP Error code extension statusMessage: type: string example: "Data Successfully Retrieved" transactionId: type: string description: "Client generated Id to include for tracing requests." data: type: array description: List of all receiver's msisdn and intended sharable amount items: $ref: '#/definitions/ReceiverInformation' _link: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/customers/2348064816493/dataShare" ConsumersListResponse: type: object properties: statusCode: type: string description: HTTP code extension statusMessage: type: string example: "Success" transactionId: type: string description: "Client generated Id to include for tracing requests." data: type: object properties: consumerList: type: array description: List of all consumers' msisdns linked to provider msisdn items: $ref: '#/definitions/ConsumerInformation' _link: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/customers/256789999781/dataShare" Error: properties: transactionId: type: string description: "Unique ID generated by the API per request for tracking purpose." sequenceNo: type: string description: "A unique id for tracking request/response on MADAPI" timestamp: type: string format: date-time description: "Timestamps of Error" example: "2020-04-02T07:29:25.593+0000" statusCode: type: string description: "Error Code" example: "1000" error: type: "string" description: "Short Description" example: "NOT_FOUND" message: type: string description: "More Error details and corrective measures" example: "" path: type: string description: "The path to the request" example: "https://api.mtn.com/v1/"