{ "info": { "name": "MTN Customer Profiles API", "schema": "https:\/\/schema.getpostman.com\/json\/collection\/v2.1.0\/collection.json" }, "item": [ { "name": "View customer profile", "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", "request": { "auth": [], "method": "Get", "header": [ { "key": "Content-Type", "name": "Content-Type", "value": "application\/json", "type": "application\/json", "description": "" } ], "url": { "raw": "api.mtn.com\/customers\/{customerId}", "protocol": "https", "host": [ "api", "mtn", "com" ], "path": [ "v1", "customers", "customers", "{customerId}" ], "query": [ { "key": "propset", "value": "", "required": 0, "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`\"" } ] } }, "response": [ { "code": 200, "status": "OK", "name": "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": { "customerId": { "type": "string" }, "locations": { "data": { "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" } }, "_link": { "self": { "href": { "type": "string", "description": "" } } } }, "plans": { "data": { "type": { "type": "string", "description": "The billing type of the plan.", "enum": [ "Prepaid", "Postpaid", "Hybrid" ] }, "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" }, "balance": { "data": { "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" } } } }, "_link": { "self": { "href": { "type": "string", "description": "" } } } }, "loans": { "data": { "_link": { "self": { "href": { "type": "string", "description": "" } } }, "status": { "type": "string", "enum": [ "FAILED", "COMPLETED", "INITED" ] }, "transactionId": { "type": "string" } }, "_link": { "self": { "href": { "type": "string", "description": "" } } } }, "account": { "data": { "accountName": { "type": "string", "example": "MoMo" }, "accountId": { "type": "string" }, "description": { "type": "string", "description": "Detailed description of account" }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "_links": { "self": { "href": { "type": "string" }, "type": { "type": "string", "example": "POST" } } } }, "kyc": { "data": { "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": { "type": "string", "default": "", "description": "Male,Female" }, "firstName": { "type": "string", "description": "Name", "example": "First n Middle" }, "lastName": { "type": "string", "description": "Surname", "example": "Surname" } }, "_link": { "self": { "href": { "type": "string", "description": "" } } } }, "devices": { "data": { "devices": { "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": { "unit": { "type": "string", "default": "", "description": "month,days" }, "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\u2019s 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": { "self": { "href": { "type": "string", "description": "" } } } }, "transactions-summaries": { "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": { "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": { "withdrawals": { "lastWithdrawalsDate": { "type": "string", "format": "date", "description": "the " }, "maxWithdrawals-6months": { "type": "string", "description": "the " }, "quantities": { "numberOfWithdrawals-1months": { "type": "string", "description": "the " }, "numberOfWithdrawals-3months": { "type": "string", "description": "the " }, "numberOfWithdrawals-6months": { "type": "string", "description": "the " } }, "amounts": { "totalWithdrawalsAmounts-1months": { "type": "string", "description": "the " }, "totalWithdrawalsAmounts-3months": { "type": "string", "description": "the " }, "totalWithdrawalsAmounts-6months": { "type": "string", "description": "the " } }, "acceptors": { "numberOfAcceptors-1months": { "type": "string", "description": "the " }, "numberOfAcceptors-3months": { "type": "string", "description": "the " }, "numberOfAcceptors-6months": { "type": "string", "description": "the " } } }, "deposits": { "lastDepositsDate": { "type": "string", "format": "date", "description": "the ", "example": "2017" }, "maxDeposits-6months": { "type": "string", "description": "the " }, "quantities": { "numberOfDeposits-1months": { "type": "string", "description": "the " }, "numberOfDeposits-3months": { "type": "string", "description": "the " }, "numberOfDeposits-6months": { "type": "string", "description": "the " } }, "amounts": { "amountOfDeposits-1months": { "type": "string", "description": "the " }, "amountOfDeposits-3months": { "type": "string", "description": "the " }, "amountOfDeposits-6months": { "type": "string", "description": "the " } }, "acceptors": { "numberOfAcceptors-1months": { "type": "string", "description": "the " }, "numberOfAcceptors-3months": { "type": "string", "description": "the " }, "numberOfAcceptors-6months": { "type": "string", "description": "the " } } }, "billPayments": { "lastBillPaymentsDate": { "type": "string", "format": "date", "description": "the ", "example": "2017" }, "maxBillPayments-6months": { "type": "string", "description": "the " }, "quantities": { "numberOfBillPayments-1months": { "type": "string", "description": "the " }, "numberOfBillPayments-3months": { "type": "string", "description": "the " }, "numberOfBillPayments-6months": { "type": "string", "description": "the " } }, "amounts": { "amountOfBillPayments-1months": { "type": "string", "description": "the " }, "amountOfBillPayments-3months": { "type": "string", "description": "the " }, "amountOfBillPayments-6months": { "type": "string", "description": "the " } }, "acceptors": { "numberOfAcceptors-1months": { "type": "string", "description": "the " }, "numberOfAcceptors-3months": { "type": "string", "description": "the " }, "numberOfAcceptors-6months": { "type": "string", "description": "the " } } }, "send": { "lastSendDate": { "type": "string", "format": "date", "description": "the ", "example": "2017" }, "maxSend-6months": { "type": "string", "description": "the " }, "quantities": { "numberOfSend-1months": { "type": "string", "description": "the " }, "numberOfSend-3months": { "type": "string", "description": "the " }, "numberOfSend-6months": { "type": "string", "description": "the " } }, "amounts": { "amountOfSend-1months": { "type": "string", "description": "the " }, "amountOfSend-3months": { "type": "string", "description": "the " }, "amountOfSend-6months": { "type": "string", "description": "the " } }, "acceptors": { "numberOfAcceptors-1months": { "type": "string", "description": "the " }, "numberOfAcceptors-3months": { "type": "string", "description": "the " }, "numberOfAcceptors-6months": { "type": "string", "description": "the " } } }, "received": { "lastReceivedDate": { "type": "string", "format": "date", "description": "the ", "example": "2017" }, "time-periods": { "1-months": { "totalReceived": { "type": "string", "description": "the " }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityReceived": { "type": "string", "description": "the " } }, "3-months": { "totalReceived": { "type": "string", "description": "the " }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityReceived": { "type": "string", "description": "the " } }, "6-months": { "totalReceived": { "type": "string", "description": "the " }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityReceived": { "type": "string", "description": "the " }, "maxReceived": { "type": "string", "description": "the " } } } }, "transfers": { "lastTransfersDate": { "type": "string", "format": "date", "description": "the ", "example": "2017" }, "time-periods": { "1-months": { "totalTransfers": { "type": "string", "description": "the " }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityTransfers": { "type": "string", "description": "the " } }, "3-months": { "totalTransfers": { "type": "string", "description": "the " }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityTransfers": { "type": "string", "description": "the " } }, "6-months": { "totalTransfers": { "type": "string" }, "totalAcceptors": { "type": "string", "description": "the " }, "quantityTransfers": { "type": "string", "description": "the " }, "maxTransfers": { "type": "string", "description": "the " } } } } }, "gsm": { "activity": { "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": { "1-months": { "numberOfActiveDays": { "type": "string", "description": "the " }, "numberOfTimesBlocked": { "type": "string", "description": "Number of times blocked (post- \uf0fc 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": { "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": { "time-periods": { "1-months": { "numberOfLoans": { "type": "string", "description": "Number of loans, for the last 1 month" } }, "3-months": { "numberOfLoans": { "type": "string", "description": "Number of loans, for the last 1 month" } }, "6-months": { "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" } } } }, "_links": { "self": { "href": { "type": "string", "description": "" } } } }, "body": "{\"customerId\":\"string\",\"locations\":{\"data\":{\"country\":\"string\",\"operator\":\"string\"},\"_link\":{\"self\":{\"href\":\"string\"}}},\"plans\":{\"data\":{\"type\":\"string\",\"status\":\"string\",\"startDate\":\"string\",\"endDate\":\"string\",\"balance\":{\"data\":{\"balanceType\":\"string\",\"amount\":\"string\",\"currency\":\"string\",\"expiryDate\":\"string\"}}},\"_link\":{\"self\":{\"href\":\"string\"}}},\"loans\":{\"data\":{\"_link\":{\"self\":{\"href\":\"string\"}},\"status\":\"string\",\"transactionId\":\"string\"},\"_link\":{\"self\":{\"href\":\"string\"}}},\"account\":{\"data\":{\"accountName\":\"string\",\"accountId\":\"string\",\"description\":\"string\",\"status\":\"string\"},\"_links\":{\"self\":{\"href\":\"string\",\"type\":\"string\"}}},\"kyc\":{\"data\":{\"idType\":\"string\",\"idNumber\":\"string\",\"dateOfBirth\":\"string\",\"gender\":\"string\",\"firstName\":\"string\",\"lastName\":\"string\"},\"_link\":{\"self\":{\"href\":\"string\"}}},\"devices\":{\"data\":{\"devices\":{\"deviceId\":\"string\",\"deviceMake\":\"string\",\"IMSI\":\"string\",\"IMEI\":\"string\",\"timePeriods\":{\"unit\":\"string\",\"value\":\"string\"},\"numberOfIMSIs\":\"string\",\"numberOfIMEIs\":\"string\",\"primaryUCID\":\"string\",\"primaryUSID\":\"string\",\"secondaryUCID\":\"string\",\"secondaryUSID\":\"string\"}},\"_links\":{\"self\":{\"href\":\"string\"}}},\"transactions-summaries\":{\"requestId\":\"string\",\"dateRange\":\"string\",\"data\":{\"marketingFlag\":true,\"lendingFlag\":true,\"momo\":{\"withdrawals\":{\"lastWithdrawalsDate\":\"string\",\"maxWithdrawals-6months\":\"string\",\"quantities\":{\"numberOfWithdrawals-1months\":\"string\",\"numberOfWithdrawals-3months\":\"string\",\"numberOfWithdrawals-6months\":\"string\"},\"amounts\":{\"totalWithdrawalsAmounts-1months\":\"string\",\"totalWithdrawalsAmounts-3months\":\"string\",\"totalWithdrawalsAmounts-6months\":\"string\"},\"acceptors\":{\"numberOfAcceptors-1months\":\"string\",\"numberOfAcceptors-3months\":\"string\",\"numberOfAcceptors-6months\":\"string\"}},\"deposits\":{\"lastDepositsDate\":\"string\",\"maxDeposits-6months\":\"string\",\"quantities\":{\"numberOfDeposits-1months\":\"string\",\"numberOfDeposits-3months\":\"string\",\"numberOfDeposits-6months\":\"string\"},\"amounts\":{\"amountOfDeposits-1months\":\"string\",\"amountOfDeposits-3months\":\"string\",\"amountOfDeposits-6months\":\"string\"},\"acceptors\":{\"numberOfAcceptors-1months\":\"string\",\"numberOfAcceptors-3months\":\"string\",\"numberOfAcceptors-6months\":\"string\"}},\"billPayments\":{\"lastBillPaymentsDate\":\"string\",\"maxBillPayments-6months\":\"string\",\"quantities\":{\"numberOfBillPayments-1months\":\"string\",\"numberOfBillPayments-3months\":\"string\",\"numberOfBillPayments-6months\":\"string\"},\"amounts\":{\"amountOfBillPayments-1months\":\"string\",\"amountOfBillPayments-3months\":\"string\",\"amountOfBillPayments-6months\":\"string\"},\"acceptors\":{\"numberOfAcceptors-1months\":\"string\",\"numberOfAcceptors-3months\":\"string\",\"numberOfAcceptors-6months\":\"string\"}},\"send\":{\"lastSendDate\":\"string\",\"maxSend-6months\":\"string\",\"quantities\":{\"numberOfSend-1months\":\"string\",\"numberOfSend-3months\":\"string\",\"numberOfSend-6months\":\"string\"},\"amounts\":{\"amountOfSend-1months\":\"string\",\"amountOfSend-3months\":\"string\",\"amountOfSend-6months\":\"string\"},\"acceptors\":{\"numberOfAcceptors-1months\":\"string\",\"numberOfAcceptors-3months\":\"string\",\"numberOfAcceptors-6months\":\"string\"}},\"received\":{\"lastReceivedDate\":\"string\",\"time-periods\":{\"1-months\":{\"totalReceived\":\"string\",\"totalAcceptors\":\"string\",\"quantityReceived\":\"string\"},\"3-months\":{\"totalReceived\":\"string\",\"totalAcceptors\":\"string\",\"quantityReceived\":\"string\"},\"6-months\":{\"totalReceived\":\"string\",\"totalAcceptors\":\"string\",\"quantityReceived\":\"string\",\"maxReceived\":\"string\"}}},\"transfers\":{\"lastTransfersDate\":\"string\",\"time-periods\":{\"1-months\":{\"totalTransfers\":\"string\",\"totalAcceptors\":\"string\",\"quantityTransfers\":\"string\"},\"3-months\":{\"totalTransfers\":\"string\",\"totalAcceptors\":\"string\",\"quantityTransfers\":\"string\"},\"6-months\":{\"totalTransfers\":\"string\",\"totalAcceptors\":\"string\",\"quantityTransfers\":\"string\",\"maxTransfers\":\"string\"}}}},\"gsm\":{\"activity\":{\"daysSinceLastActive\":\"string\",\"topupMethod\":\"string\",\"time-periods\":{\"1-months\":{\"numberOfActiveDays\":\"string\",\"numberOfTimesBlocked\":\"string\",\"airtimeUtilisation\":\"string\",\"daysAirtimeBalanceBelow\":\"string\",\"topupAmount\":\"string\",\"averageTopupAmount\":\"string\",\"totalOutboundCalls\":\"string\",\"distinctOutboundCalls\":\"string\",\"totalInboundCalls\":\"string\",\"distinctInboundCalls\":\"string\",\"dataUsage\":\"string\",\"lastDataBundlePurchaseDate\":\"string\",\"daysDataBalanceBelow\":\"string\",\"averageDataBundleSize\":\"string\",\"me2u\":{\"me2uNumberAirtimeReceived\":\"string\",\"me2uAmountAirtimeReceived\":\"string\"}}}}},\"momo-loans\":{\"time-periods\":{\"1-months\":{\"numberOfLoans\":\"string\"},\"3-months\":{\"numberOfLoans\":\"string\"},\"6-months\":{\"numberOfLoans\":\"string\"}},\"totalLoansAmount\":\"string\",\"firstLoansDate\":\"string\",\"lastLoansDate\":\"string\",\"numberOverdue\":\"string\",\"totalTerm\":\"string\",\"maxTerm\":\"string\",\"lastOverdueDate\":\"string\"}}},\"_links\":{\"self\":{\"href\":\"string\"}}}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 207, "status": "Multi-Status", "name": "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", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 400, "status": "Bad Request", "name": "Bad Request", "schema": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "body": "{\"error\":\"string\",\"error_description\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 401, "status": "Unauthorized", "name": "Unauthorized", "schema": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "body": "{\"error\":\"string\",\"error_description\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 403, "status": "Forbidden", "name": "Forbidden", "schema": { "error": { "type": "string" }, "error_description": { "type": "string" } }, "body": "{\"error\":\"string\",\"error_description\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 404, "status": "Not Found", "name": "Customer not found", "schema": [], "body": "[]", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 405, "status": "Method Not Allowed", "name": "Method Not allowed", "schema": { "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": "" } }, "body": "{\"timestamp\":\"string\",\"status\":\"string\",\"error\":\"string\",\"message\":\"string\",\"path\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] }, { "code": 500, "status": "Internal Server Error", "name": "Internal Server Error", "schema": { "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": "" } }, "body": "{\"timestamp\":\"string\",\"status\":\"string\",\"error\":\"string\",\"message\":\"string\",\"path\":\"string\"}", "header": [ { "key": "Content-Type", "value": "application\/json", "description": "Sending as JSON", "type": "string" } ] } ] } ] }