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.
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/<path>"
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/<path>"
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 u
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-mtn-customer-profiles-api-v2-product.yml