swagger: "2.0" info: version: "v1.11" title: MTN Customer Profiles API description: An API to retrieve the profile of an MTN customer. Please refer to the reference guides https://developers.mtn.com/API-Reference-Guides and Response and Error Codes documents https://developers.mtn.com/ResponseCodes schemes: - https host: "api.mtn.com" basePath: "/v2" consumes: - "application/json" produces: - "application/json" 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: - ApiKeyAuth: [] - OAuth2: [] paths: /customers/{customerId}: get: description: "Retrieves the customer profile of a MTN customer. The customer profile includes 4 main objects: Location (Country and Operator), Billing Plan and related details, Subscriptions for VAS and Digital Services, Loans details, and Transactions Summaries" summary: "View customer profile" tags: - "customers" parameters: - in: "path" name: "customerId" description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123" required: true type: "string" - in: "query" name: propset type: string description: "the set of data to be retrieved. There are 2 options - `basic` will retrieve only the structure of the customer profile including the links to each resource, will `full` will retrieve all the data for each resource, which will be en expensive call. If not specified, the default will be `basic`" enum: - basic - full - CustomerProfile - name: x-authorization in: header description: 'Encrypted ECW credentials' required: false type: string - in: "query" name: "pref language" required: false description: The language in which the response is required type: "string" enum: [En,Fr] responses: 200: description: "Customer Profile object. For a successful request, it will contain all the customers details. If the customer does not have any requested data, then it will be null. E.g. if the customer does not any location set, then Country and Operator will be null." schema: $ref: "#/definitions/Customer" 207: description: "If there was an error retrieving some part of the request, then the successful request will be shown, and the remaining failed objects will be be excluded. E.g. if there was an error retrieving Balance information, then the balance object will be empty" examples: Multi-Status Response, showing valid Locations data, but plan object is null: > "location": { "data": { "country": "ZA", "operator": "MTN" }, "_links": { "self": { "href": "http://api.mtn.com/customers/27832000046/locations" } } } "plan": { "data": null, "_links": { "self": { "href": "http://api.mtn.com/customers/27832000046/plans" } } } 400: description: "Bad Request" schema: $ref: "#/definitions/ErrorDefault" 401: description: "Unauthorized" schema: $ref: "#/definitions/ErrorDefault" 403: description: "Forbidden" schema: $ref: "#/definitions/ErrorDefault" 404: description: "Customer not found" examples: The data object/envelope will be null: > { "data": null } 405: description: "Method Not allowed" schema: $ref: "#/definitions/Error" 500: description: "Internal Server Error" schema: $ref: "#/definitions/Error" /customers/upgrade-eligibility/{customerId}: get: description: "Retrieves the Customer’s Upgrade Eligibility" summary: "Get customer’s upgrade eligibility" tags: - "customers" parameters: - in: "path" name: "customerId" description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123" required: true type: "string" - in: "body" name: profileBody description: Profile of the customer (As stored in the 3PP Cache) required: true schema: $ref: '#/definitions/CustomerProfile' responses: 200: description: "For a successful request, it will contain the details like Eligibility Status, Date and URL." schema: $ref: "#/definitions/CustomerUpgradeEligibilityResponse" "400": description: Bad Request schema: $ref: '#/definitions/ErrorNew' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorNew' "403": description: Forbidden schema: $ref: '#/definitions/ErrorNew' "404": description: Not Found schema: $ref: '#/definitions/ErrorNew' "405": description: Method No Allowed schema: $ref: '#/definitions/ErrorNew' "406": description: Not acceptable schema: $ref: '#/definitions/ErrorNew' "415": description: Unsopported media Type schema: $ref: '#/definitions/ErrorNew' "500": description: Internal Server Error schema: $ref: '#/definitions/ErrorNew' /customers/{customerId}/tenure: get: description: "Retrieves the Customer’s Tenure information" summary: "Get customer’s tenure" tags: - "customers" parameters: - in: "path" name: "customerId" description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123" required: true type: "string" - in: header name: transactionId type: string required: false description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller" x-example: c125d1e7-843f-410f-9252-71a55ec7cb92 - name: targetSystem in: query description: Target system type: string required: false x-example: EVA responses: 200: description: "For a successful request, it will contain the Customer’s Tenure information" schema: $ref: "#/definitions/CustomerTenureResponse" "400": description: Bad Request schema: $ref: '#/definitions/ErrorNew' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorNew' "403": description: Forbidden schema: $ref: '#/definitions/ErrorNew' "404": description: Not Found schema: $ref: '#/definitions/ErrorNew' "405": description: Method No Allowed schema: $ref: '#/definitions/ErrorNew' "406": description: Not acceptable schema: $ref: '#/definitions/ErrorNew' "415": description: Unsopported media Type schema: $ref: '#/definitions/ErrorNew' "500": description: Internal Server Error schema: $ref: '#/definitions/ErrorNew' /customers/{customerId}/activityStatus: get: description: "Retrieves the Customer’s Activity Status" summary: "Get customer’s activity status" tags: - "customers" parameters: - in: "path" name: "customerId" description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123" required: true type: "string" - in: header name: transactionId type: string required: false description: "A unique ID for tracking a particular transaction, optional and to be generated if not passed by the API caller" x-example: c125d1e7-843f-410f-9252-71a55ec7cb92 - name: targetSystem in: query description: Target system type: string required: false x-example: EVA responses: 200: description: "For a successful request, it will contain the Customer’s activity status information" schema: $ref: "#/definitions/CustomerStatusResponse" "400": description: Bad Request schema: $ref: '#/definitions/ErrorNew' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorNew' "403": description: Forbidden schema: $ref: '#/definitions/ErrorNew' "404": description: Not Found schema: $ref: '#/definitions/ErrorNew' "405": description: Method No Allowed schema: $ref: '#/definitions/ErrorNew' "406": description: Not acceptable schema: $ref: '#/definitions/ErrorNew' "415": description: Unsopported media Type schema: $ref: '#/definitions/ErrorNew' "500": description: Internal Server Error schema: $ref: '#/definitions/ErrorNew' /customers/{customerId}/set-lang: put: description: "Sets the Customer’s Language Preference" summary: "Sets the Customer’s Language Preference" tags: - "Customer Characteristics" parameters: - in: "path" name: "customerId" description: "ID of the customer. It could be MSISDN, email address, or any other customer identifier. if id is msisdn, format must be E.123" required: true type: "string" - in: "header" name: transactionId description: Transaction Id as sent by the 3PP type: "string" - in: "query" name: lang type: "string" description: | The preferred language. * SA Example:ZULU,ENGLISH,SESOTHO,XHOSA,TSONGA,AFRIKAANS. * NG Examples: ARA,DUT,FRE,HAU,IBO,ND1,ND2,ND3,ND4,ND5,ND6,ND7,OTH,YOR,en-US,CPE - in: "query" name: customerIdType type: "string" description: The preferred language. enum: - NIN - MSISDN responses: 200: description: "Successful request" schema: $ref: "#/definitions/CustomerSetLangResponse" "400": description: Bad Request schema: $ref: '#/definitions/ErrorNew' "401": description: Unauthorized schema: $ref: '#/definitions/ErrorNew' "403": description: Forbidden schema: $ref: '#/definitions/ErrorNew' "404": description: Not Found schema: $ref: '#/definitions/ErrorNew' "405": description: Method No Allowed schema: $ref: '#/definitions/ErrorNew' "406": description: Not acceptable schema: $ref: '#/definitions/ErrorNew' "415": description: Unsopported media Type schema: $ref: '#/definitions/ErrorNew' "500": description: Internal Server Error schema: $ref: '#/definitions/ErrorNew' /customers/{customerId}/summary: get: tags: - "Member Summary" summary: "Member Summary" description: "Retrieves the acountholder's (member summary) from ayo ." produces: - "application/json" parameters: - name: customerId in: path description: ID value of the Accountholder/Customer i.e. MSISDN - ex-27123456788 required: true type: string - name: id in: header type: string description: id of the customer ex- SAID, Passportid etc - name: transactionDate in: header description: Transaction date ex '2022-06-03T14:19:38.996Z' type: string - name: transactionId in: header description: transactionId is the unique identifier to track the request ex '202rtre5t5567trt67y89' type: string - name: targetSystem in: header description: target system is backend for which the request is initiated ex- AYO-MTN-ZAF type: string required: true - name: idType in: header description: idType defines the type of customerid ex- passport etc type: string - name: x-origin-channelId in: header description: information on originator ex-USSD type: string responses: "200": description: "Successful response" schema: $ref: "#/definitions/ayoSummaryResponse" "400": description: "Bad Request" schema: $ref: "#/definitions/ayoSummaryError" "401": description: "UnAuthorized" schema: $ref: "#/definitions/ayoSummaryError" "403": description: "Forbidden" schema: $ref: "#/definitions/ayoSummaryError" "500": description: "Internal Server Error" schema: $ref: "#/definitions/ayoSummaryError" definitions: Customer: type: "object" required: - "customerId" - "_links" properties: transactionId: type: "string" description: "Transaction Id of the request" statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '0000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client customerId: type: "string" customerSystem: type: "string" description: "Type of Customer" characteristics: type: "array" description: Customer characteristics items: $ref: "#/definitions/CustomerCharacteristics" locations: type: "object" description: "The location of customer. Location includes Country and Network Operator" $ref: "#/definitions/CustomerLocations" plans: type: array items: $ref: "#/definitions/CustomerPlans" loans: type: "object" description: "the customers loan and eligibility details" $ref: "#/definitions/CustomerLoans" account: type: array items: $ref: "#/definitions/AccountRef" kyc: type: array items: $ref: "#/definitions/KYC" devices: type: array items: $ref: "#/definitions/Devices" transactions-summaries: $ref: "#/definitions/transactions-summaries" _links: type: "string" description: "link to retrieve the customer profile" $ref: "#/definitions/CustomerLinks" CustomerProfile: type: "object" required: - "customerId" - "_links" properties: transactionId: type: "string" description: "Transaction Id of the request" customerId: type: "string" customerSystem: type: "string" description: "Type of Customer" characteristics: type: "array" description: Customer characteristics items: $ref: "#/definitions/CustomerCharacteristics" plans: type: array items: $ref: "#/definitions/CustomerPlans" account: type: array items: $ref: "#/definitions/AccountRef" kyc: type: array items: $ref: "#/definitions/KYC" CustomerLinks: type: "object" required: - "self" properties: self: type: "object" required: - "href" description: "" properties: href: type: "string" description: "" Any: {} CustomerCharacteristics: type: "object" description: >- Describes a given characteristic of an object or entity through a name/value pair. required: - name - value properties: name: type: string description: Name of the characteristic valueType: type: string description: Data type of the value of the characteristic value: $ref: '#/definitions/Any' description: The value of the characteristic _link: type: "string" description: "The link to retrieve the characteristics for a customer." $ref: "#/definitions/CustomerLinks" example: "https://api.mtn.com/v1/customers/27832000000/characterictics" CustomerLocations: type: "object" required: - "_link" properties: data: type: "object" $ref: "#/definitions/Locations" _link: type: "string" description: "The link to retrieve the location of customer" $ref: "#/definitions/CustomerLinks" example: "https://api.mtn.com/v1/customers/27832000000/locations" Locations: type: "object" required: - "country" - "operator" properties: country: type: "string" description: "The country that the customer MSISDN was provisioned in." example: "South Africa" operator: type: "string" description: "The network operator that the customer MSISDN was provisioned for." example: "MTN" CustomerPlans: type: "object" required: - "_link" properties: category: type: string description: Will contain the identifier for product line. Example - GSM, Digital Services, Mobile Money etc. data: type: array items: $ref: "#/definitions/Plans" _link: type: "string" description: "The link to retrieve the plan for a customer." $ref: "#/definitions/CustomerLinks" example: "https://api.mtn.com/v1/customers/27832000000/plan" Plans: type: "object" required: - "type" - "status" - "startDate" - "endDate" - "balance" description: "The plan details for the customer." properties: type: type: "string" description: "The billing type of the plan." enum: - "Prepaid" - "Postpaid" - "Hybrid" id: type: "string" status: type: "string" description: "The current status of the plan." enum: - "Active" - "Suspended" - "Inactive" - "RICA Barred" - "Blacklisted" startDate: type: "string" description: "The date the customer was created/provisioned" format: date-time endDate: type: "string" description: "The date the plan will be deactivated." format: date-time maxModify: type: "string" description: "Number of allowed max modifications. Used to fetch Caller Feel/Tune subscriber details" example: 5 usedModify: type: "string" description: "Number of used modifications. Used to fetch Caller Feel/Tune subscriber details" example: 1 balance: type: "array" description: "The account balance details of a customer" items: $ref: "#/definitions/CustomerBalances" CustomerBalances: type: "object" properties: data: type: "object" required: - "balanceType" - "amount" - "currency" - "expiryDate" properties: balanceType: type: "string" description: "Identifies the type of balance. A customer plan may have multiple types of balances for different usage, for example, voice, SMS, and game services." example: "VOICE" amount: type: "string" description: "Amount of balance." example: "26861" currency: type: "string" description: "ISO 4217 three-letter ISO code for the currency." example: "ZAR" expiryDate: type: "string" format: date-time description: "Expiry Date of the account." example: "2019-12-31T12:00:00" CustomerLoans: type: "object" required: - "_link" properties: data: type: "object" $ref: "#/definitions/Loans" _link: type: "string" description: "The link to retrieve the customers MoMo details." $ref: "#/definitions/CustomerLinks" example: "https://api.mtn.com/v1/customers/27832000000/loans" Loans: type: object required: - "customerId" description: "The loans details of a customer, if it exists" properties: _link: type: array xml: name: link attribute: false wrapped: false items: $ref: '#/definitions/CustomerLinks' status: type: string enum: - FAILED - COMPLETED - INITED transactionId: type: string Band: type: object properties: bandGroup: type: integer format: int32 bandName: type: string title: Band Eligibility: type: object properties: _links: type: array xml: name: link attribute: false wrapped: false items: $ref: '#/definitions/Link' bands: type: array items: $ref: '#/definitions/Band' status: type: string enum: - ELIGIBLE - NE_LOAN - NE_TCL_REACHED title: Eligibility Link: type: object properties: deprecation: type: string xml: name: deprecation attribute: true wrapped: false href: type: string xml: name: href attribute: true wrapped: false hreflang: type: string xml: name: hreflang attribute: true wrapped: false media: type: string xml: name: media attribute: true wrapped: false rel: type: string xml: name: rel attribute: true wrapped: false templated: type: boolean title: type: string xml: name: title attribute: true wrapped: false type: type: string xml: name: type attribute: true wrapped: false title: Link Error: properties: timestamp: type: "string" format: "date-time" description: "Error response code" status: type: "string" description: "Text explaining the reason for the error" error: type: "string" message: type: "string" description: "More error details and corrective measures" path: type: "string" description: "" ErrorDefault: properties: error: type: "string" error_description: type: "string" ErrorNew: type: object required: - "statusCode" - "statusMessage" properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '1000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: This is the same transactionId that is sent in the request timestamp: type: string format: date-time description: Timestamp of the error example: "2019-08-23T07:29:25.593+0000" _links: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/" CustomerUpgradeEligibilityResponse: type: object properties: statusCode: type: string example: "0000" statusMessage: type: string example: "Request Successfully processed" transactionId: type: string description: "Client or API generated Id to include for tracing requests" data: $ref: '#/definitions/Upgrade' _links: type: "string" description: "The link to retrieve the Upgrade Eligibility for a customer." $ref: "#/definitions/links" Upgrade: type: object properties: UpgradeEligibility: type: array description: "The list of Upgrade Eligibility parameters" items: $ref: '#/definitions/UpgradeEligibilityParams' UpgradeEligibilityParams: type: "object" description: >- Describes a given characteristic of an object or entity through a name/value pair. required: - name - value properties: name: type: string description: Name of the characteristic example: Eligibility Date valueType: type: string description: Data type of the value of the characteristic example: date-time value: $ref: '#/definitions/Any' description: The value of the characteristic example: "2019-08-23T07:29:25.593+0000" links: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/" CustomerSetLangResponse: type: "object" properties: statusCode: type: string example: "0000" statusMessage: type: string example: "Request Successfully processed" transactionId: type: string description: "Client or API generated Id to include for tracing requests" example: "85499086" customerId: type: string example: "234806589013" transactionReference: type: string example: "20220202134228" data: $ref: '#/definitions/setLang' _links: type: "string" description: "The link to retrieve the Upgrade Eligibility for a customer." $ref: "#/definitions/links" setLang: type: "object" properties: lang: type: string example: "AFRIKAANS" CustomerTenureResponse: type: "object" properties: statusCode: type: string example: "0000" statusMessage: type: string example: "Request Successfully processed" transactionId: type: string description: "Client or API generated Id to include for tracing requests" example: "85499086" customerId: type: string example: "234806589013" data: $ref: '#/definitions/tenure' tenure: type: "object" properties: tenure: type: integer example: "12" CustomerStatusResponse: type: "object" properties: statusCode: type: string example: "0000" statusMessage: type: string example: "Request Successfully processed" transactionId: type: string description: "Client or API generated Id to include for tracing requests" example: "85499086" customerId: type: string example: "234806589013" data: $ref: '#/definitions/status' status: type: "object" properties: activityStatus: type: string example: "Active" AccountRef: properties: data: type: object properties: accountName: type: string example: MoMo accountId: type: string description: type: string description: Detailed description of account status: type: string enum: [active, inactive] _links: type: object properties: self: type: object properties: href: type: string type: type: string example: POST KYC: properties: data: type: object properties: idType: type: string description: "Legal ID Type" example: "South African ID" idNumber: type: string description: "Legal ID Number/Reference" example: "8002143987083" dateOfBirth: type: string format: date description: "Date of Birth" pattern: "YYYY-MM-DD" example: "1980-02-14" gender: $ref: "#/definitions/GenderEnum" firstName: type: string description: "Name" example: "First n Middle" lastName: type: string description: "Surname" example: "Surname" _link: type: "string" description: "The link to retrieve the customers KYC details." $ref: "#/definitions/CustomerLinks" GenderEnum: type: "string" title: "Gender Enum" example: "Male" enum: - "Male" - "Female" Devices: type: object properties: data: type: object properties: devices: type: array items: properties: deviceId: type: string description: "an identifier for each device. This will be a unique key per device, the format will be a string " example: "Should" deviceMake: type: string description: "Make of current device" example: "Apple iPhone X" IMSI: type: string description: "Last known IMSI. Relates to the SIM used by the MSISDN" example: "310150123456789" IMEI: type: string description: "Last known IMEI. Unique identifier of Mobile Device used by the MSISDN" example: "990000862471854" timePeriods: type: object properties: unit: $ref: "#/definitions/timePeriodEnum" value: type: string description: the value of the timePeriods 'unit' field. E.g. if unit is 'month', then this will represent how many months example: "1" numberOfIMSIs: type: string description: "The number of unique IMSIs that was used by the MSISDN in the last measured period" example: "4" numberOfIMEIs: type: string description: "The number of unique IMEI’s that was used by the MSISDN in the last measured period" example: "1" primaryUCID: type: string description: "Primary Unique Customer Id" primaryUSID: type: string description: "Primary Unique Service Id" secondaryUCID: type: string description: "Secondary Unique Customer Id" secondaryUSID: type: string description: "Secondary Unique Service Id" _links: $ref: "#/definitions/CustomerLinks" timePeriodEnum: type: string description: "a time period for which data is available. Usually data is available for multiple time periods, like 1 month, 3 month, and 6 month. Each time period will be represented as a separate array" enum: - "month" - "days" transactions-summaries: properties: requestId: type: string description: "The requestId that was used by the client" dateRange: type: string description: "The date range used by the client, to request customer data for a specific time period" data: type: object properties: marketingFlag: type: boolean description: "Flag set for this partner, or should this should be an object, of flags per partner" lendingFlag: type: boolean description: "This should be an object, of flags per partner" momo: type: object properties: withdrawals: $ref: "#/definitions/withdrawals" deposits: $ref: "#/definitions/deposits" billPayments: $ref: "#/definitions/billPayments" send: $ref: "#/definitions/send" received: $ref: "#/definitions/received" transfers: $ref: "#/definitions/transfers" gsm: type: object properties: activity: $ref: "#/definitions/activity" momo-loans: $ref: "#/definitions/momo-loans" withdrawals: type: object properties: lastWithdrawalsDate: type: string format: date description: "the " maxWithdrawals-6months: type: string description: "the " quantities: type: object properties: numberOfWithdrawals-1months: type: string description: "the " numberOfWithdrawals-3months: type: string description: "the " numberOfWithdrawals-6months: type: string description: "the " amounts: type: object properties: totalWithdrawalsAmounts-1months: type: string description: "the " totalWithdrawalsAmounts-3months: type: string description: "the " totalWithdrawalsAmounts-6months: type: string description: "the " acceptors: type: object properties: numberOfAcceptors-1months: type: string description: "the " numberOfAcceptors-3months: type: string description: "the " numberOfAcceptors-6months: type: string description: "the " deposits: type: object properties: lastDepositsDate: type: string format: date description: "the " example: "2017" maxDeposits-6months: type: string description: "the " quantities: type: object properties: numberOfDeposits-1months: type: string description: "the " numberOfDeposits-3months: type: string description: "the " numberOfDeposits-6months: type: string description: "the " amounts: type: object properties: amountOfDeposits-1months: type: string description: "the " amountOfDeposits-3months: type: string description: "the " amountOfDeposits-6months: type: string description: "the " acceptors: type: object properties: numberOfAcceptors-1months: type: string description: "the " numberOfAcceptors-3months: type: string description: "the " numberOfAcceptors-6months: type: string description: "the " billPayments: type: object properties: lastBillPaymentsDate: type: string format: date description: "the " example: "2017" maxBillPayments-6months: type: string description: "the " quantities: type: object properties: numberOfBillPayments-1months: type: string description: "the " numberOfBillPayments-3months: type: string description: "the " numberOfBillPayments-6months: type: string description: "the " amounts: type: object properties: amountOfBillPayments-1months: type: string description: "the " amountOfBillPayments-3months: type: string description: "the " amountOfBillPayments-6months: type: string description: "the " acceptors: type: object properties: numberOfAcceptors-1months: type: string description: "the " numberOfAcceptors-3months: type: string description: "the " numberOfAcceptors-6months: type: string description: "the " send: type: object properties: lastSendDate: type: string format: date description: "the " example: "2017" maxSend-6months: type: string description: "the " quantities: type: object properties: numberOfSend-1months: type: string description: "the " numberOfSend-3months: type: string description: "the " numberOfSend-6months: type: string description: "the " amounts: type: object properties: amountOfSend-1months: type: string description: "the " amountOfSend-3months: type: string description: "the " amountOfSend-6months: type: string description: "the " acceptors: type: object properties: numberOfAcceptors-1months: type: string description: "the " numberOfAcceptors-3months: type: string description: "the " numberOfAcceptors-6months: type: string description: "the " received: type: object properties: lastReceivedDate: type: string format: date description: "the " example: "2017" time-periods: type: object properties: 1-months: type: object properties: totalReceived: type: string description: "the " totalAcceptors: type: string description: "the " quantityReceived: type: string description: "the " 3-months: type: object properties: totalReceived: type: string description: "the " totalAcceptors: type: string description: "the " quantityReceived: type: string description: "the " 6-months: type: object properties: totalReceived: type: string description: "the " totalAcceptors: type: string description: "the " quantityReceived: type: string description: "the " maxReceived: type: string description: "the " transfers: type: object properties: lastTransfersDate: type: string format: date description: "the " example: "2017" time-periods: type: object description: "the " properties: 1-months: type: object description: "the " properties: totalTransfers: type: string description: "the " totalAcceptors: type: string description: "the " quantityTransfers: type: string description: "the " 3-months: type: object properties: totalTransfers: type: string description: "the " totalAcceptors: type: string description: "the " quantityTransfers: type: string description: "the " 6-months: type: object properties: totalTransfers: type: string totalAcceptors: type: string description: "the " quantityTransfers: type: string description: "the " maxTransfers: type: string description: "the " gsm: type: object title: "gsm object" properties: networkRegistrationDate: type: string format: date description: "the date the customer was initially registered on the network. This is also found in Plans API - startdate " networkPaymentType: type: string example: "Prepaid" description: "the date the customer was initially registered on the network. This is also found in Plans API - type. This should be removed from here " activity: type: object description: "Actvity related to GSM calls, data bundles, and airtime" properties: daysSinceLastActive: type: string description: "Number of days since last activity" topupMethod: type: string description: "Method used to topup airtime (and data?). Should this be a enum, of known types?" time-periods: type: object properties: 1-months: type: object properties: numberOfActiveDays: type: string description: "the " numberOfTimesBlocked: type: string description: "Number of times blocked (post-  paid), for the last 1 month" airtimeUtilisation: type: string description: "the " daysAirtimeBalanceBelow: type: string description: "Days Airtime Below XX, based on UMD, for the last 1 month" topupAmount: type: string description: "Network Topup Amount, for the last 1 month" averageTopupAmount: type: string description: "the " totalOutboundCalls: type: string description: "Number of outbound calls, for the last 1 month " distinctOutboundCalls: type: string description: "Number of Number of distinct outbound B-Parties , for the last 1 month " totalInboundCalls: type: string description: "Number of inbound calls, for the last 1 month " distinctInboundCalls: type: string description: "Number of distinct inbound B-Parties , for the last 1 month " dataUsage: type: string description: "Data usage in MB, for the last 1 month " lastDataBundlePurchaseDate: type: string description: "Date of last data bundle purchase (any data bundle), for the last 1 month " daysDataBalanceBelow: type: string description: "Days bundle balance less then 2MB, for the last 1 month" averageDataBundleSize: type: string description: "Average bundle size purchased, for the last 1 month" me2u: type: object properties: me2uNumberAirtimeReceived: type: string description: "Number of MTN Me2U airtime received, for the last 1 month" me2uAmountAirtimeReceived: type: string description: "Amount of MTN Me2U airtime received, for the last 1 month" momo-loans: type: object title: "loans object" properties: time-periods: type: object properties: 1-months: type: object properties: numberOfLoans: type: string description: "Number of loans, for the last 1 month" 3-months: type: object properties: numberOfLoans: type: string description: "Number of loans, for the last 1 month" 6-months: type: object properties: numberOfLoans: type: string description: "Number of loans, for the last 1 month" totalLoansAmount: type: string description: "tTotal loan amount" firstLoansDate: type: string format: date description: "First loan date" lastLoansDate: type: string format: date description: "Last loan date" numberOverdue: type: string description: "Number of loans overdue" totalTerm: type: string description: "Total loan term" maxTerm: type: string description: "Maximum loan term" lastOverdueDate: type: string format: date description: "Last time loan was overdue" ayoSummaryResponse: type: object required: - memberAggrementNumber - coverDetails properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. example: '0000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client example: 'success' supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful), mapped to description from the response of AYO example: 'Success' transactionId: type: string description: This is the same transactionId that is sent in the request example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4' memberAggrementNumber: type: string example: 2120000059490612 description: Personal ID Number which is the unique value provided by ayo for every customer coverDetails: description: Cover details consist of all the information related to policy associated with the customer $ref: "#/definitions/ayocoverDetails" ayocoverDetails: type: object properties: benefit: type: string example: CARE365MYFAPH description: Benefits are the additions information given to the customer as defined by AYO policyNumber: type: string example: 7132669 description: Policy Number is string value defined in AYO policyStatus: type: string example: In Force description: Policy Status is defined in three different values 'Not Takenup', 'In Force', 'Termination Notice' productCode: type: string example: MyMTN Prepaid Funeral Khava description: product code is commercial name of the product used by the customer as defined in AYO consents: type: string description: consent example: y coverPeriod: type: integer example: 6 description: Policy Cover Period is numerical value which defines the duration calculated in months coverAmount: $ref: "#/definitions/ayoAmount" totalPremium: $ref: "#/definitions/ayoAmount" ayoAmount: type: object properties: amount: type: integer example: 3000 description: amount is numerical value defined in different features like premium and cover currencyCode: type: string example: ZAR description: Currecy code is currency in which amount is defined, for southAfrica it is ZAR ayoSummaryError: type: object required: - "statusCode" - "statusMessage" - "supportMessage" - "transactionId" properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. example: '4001' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client example: 'Bad request' supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful), mapped to description from the response of AYO example: 'No policy is found per the id number.' transactionId: type: string description: This is the same transactionId that is sent in the request example: 'cdfa7bc3-cbcd-473b-a743-4fc90dcc91e4' path: type: string description: The path that caused the error example: '/27831234567/summary' method: type: string description: The HTTP method type that was used example: 'GET' type: type: string example: 'business error' description: type of error is shown for non 200 response and mapped from AYO response