An API to retrieve the profile of an MTN field agent. Please refer to the reference guides https://developers.mtn.com/getting-started and Response and Error Codes documents https://developers.mtn.com/getting-started/response-and-error-codes.
swagger: "2.0"
info:
version: "v1.0"
title: MTN Agent Profile API
description: |-
An API to retrieve the profile of an MTN field agent. Please refer to the reference guides https://developers.mtn.com/getting-started and Response and Error Codes documents https://developers.mtn.com/getting-started/response-and-error-codes
schemes:
- https
host: "api.mtn.com"
basePath: "/v1/agents"
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:
/{agentId}:
get:
description: "Retrieves the profile of a MTN field agent."
summary: "View agent profile"
tags:
- "agents"
parameters:
- in: "path"
name: "agentId"
description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
required: true
type: "string"
- name: fields
in: query
type: string
description: Filter for parts of the agent profile to be returned. Use comma-separated values
x-example: agentKyc,agentPlans,activityReport
- name: X-Authorization
in: header
type: string
description: >-
SSO Bearer token received from OAuth2.0 authentication with the
backend system
x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
responses:
200:
description: "Agent Profile object. For a successful request, it will contain all the agent's details. If the agent does not have any requested data, then it will be null."
schema:
$ref: "#/definitions/Agent"
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/agents/27832000046/locations"
}
}
}
"plan": {
"data": null,
"_links": {
"self": {
"href": "http://api.mtn.com/agents/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: "Agent 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"
/{customerId}/agentFlag:
get:
summary: "To know if any given customer Id (MSISDN) is registered as an MTN field Agent or not"
description: "To know if any given customer Id (MSISDN) is registered as an MTN field Agent or not"
tags:
- "agents"
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"
- name: X-Authorization
in: header
type: string
description: >-
SSO Bearer token received from OAuth2.0 authentication with the
backend system
x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
responses:
200:
description: OK
schema:
$ref: "#/definitions/agentFLAG"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/ErrorDefault"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/ErrorDefault"
404:
description: "Agent 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"
/{agentId}/devices:
patch:
summary: "Update device information of a registered MTN Agent"
description: "Update device information of a registered MTN Agent. E.g. Updating the IMEI the Agent's assigned Point-of-Sale device"
tags:
- "agents"
parameters:
- in: "path"
name: "agentId"
description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
required: true
type: "string"
- name: transactionId
in: header
description: Client generated request Id.
type: string
- name: X-Authorization
in: header
type: string
description: >-
SSO Bearer token received from OAuth2.0 authentication with the
backend system
x-example: eyJhbGciOiJ.IUzI1NiIsIn.R5cCI6IkpXVCJ9
- name: deviceInfo
in: body
description: Device Information
schema:
allOf:
- $ref: '#/definitions/Devices'
- type: object
properties:
geoTag:
$ref: '#/definitions/geoTagging'
responses:
201:
description: Created
schema:
allOf:
- type: object
properties:
statusCode:
type: string
description: Response status code. 0000 for success
transactionId:
type: string
description: Response transaction Id from the backend
- $ref: "#/definitions/Devices"
- type: object
properties:
geoTag:
$ref: '#/definitions/geoTagging'
- type: object
properties:
_links:
$ref: "#/definitions/AgentLinks"
400:
description: "Bad Request"
schema:
$ref: "#/definitions/Error"
401:
description: "Unauthorized"
schema:
$ref: "#/definitions/Error"
403:
description: "Forbidden"
schema:
$ref: "#/definitions/Error"
404:
description: "Agent 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"
/{agentId}/tracking/:
post:
operationId: addAppInstallationConfirmationDetails
summary: submit app installation confirmation details to the API.
description: >-
This endpoint is used to submit app installation confirmation details to the API.
tags:
- agents
parameters:
- in: "path"
name: "agentId"
description: "ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123"
required: true
type: "string"
- name: "installationConfirmationDetails"
in: body
required: true
description: "Client generated Id to include for tracing requests."
schema:
$ref: "#/definitions/installationConfirmationDetailsRequest"
responses:
"200":
description: Success
schema:
$ref: "#/definitions/installationConfirmationDetailsResponse"
"400":
description: Bad Request
schema:
$ref: "#/definitions/Error"
"401":
description: Unauthorized
schema:
$ref: "#/definitions/Error"
"403":
description: Forbidden
schema:
$ref: "#/definitions/Error"
"404":
description: Not Found
schema:
$ref: "#/definitions/Error"
"405":
description: Method Not allowed
schema:
$ref: "#/definitions/Error"
"409":
description: Conflict
schema:
$ref: "#/definitions/Error"
"500":
description: Internal Server Error
schema:
$ref: "#/definitions/Error"
definitions:
Agent:
type: object
properties:
statusCode:
type: string
description: Canonical response code. '0000' for success response
example: '0000'
agentId:
type: string
example: '2568810000034'
agentKyc:
type: array
items:
$ref: "#/definitions/AGENTKYC"
agentPlans:
type: object
$ref: "#/definitions/AGENTPLANS"
activityReport:
type: object
$ref: "#/definitions/ACTIVITYREPORT"
_link:
type: "object"
allOf:
- description: "The link to retrieve the Agent KYC details."
- $ref: "#/definitions/AgentLinks"
AgentLinks:
type: "object"
required:
- "self"
properties:
self:
type: "object"
required:
- "href"
description: ""
properties:
href:
type: "string"
description: ""
example: 'https://api.mtn.com/v1/agents/256779999781'
AGENTKYC:
type: object
properties:
data:
type: object
properties:
agentId:
type: string
description: Unique identifier for the Agent
example: DEALER789
role:
type: string
description: Role of the Agent in the agent's hierarchy
enum:
- Agent
- MasterDealer
- HandlerDealer
type:
type: string
description: Type of the agent
example: RICA
status:
type: string
description: Current status of the agent
enum:
- Active
- Suspended
- Blocked
imei:
type: string
description: IMEI of the handset that is assigned to the Agent
example: 123456789876543
registrationDate:
type: string
format: date-time
description: Date and time when the Agent was created. Should be in ISO 8601
firstName:
type: string
middleName:
type: string
lastName:
type: string
AGENTPLANS:
type: object
properties:
data:
type: object
properties:
balance:
type: array
description: The account balance details of an agent
items:
properties:
balanceType:
type: string
description: 'Identifies the type of balance. An agent plan may have multiple types of balances for different usage, for example, AgentCommission, voice, SMS, and game services.'
example: 'AgentCommission'
category:
type: string
description: Identifies the category of the balance type.
example: 'AgentCommission'
balanceDetail:
$ref: '#/definitions/BalanceDetail'
wallets:
type: array
description: The different wallets used to compute the active and unused values of this balance.
items:
$ref: '#/definitions/Wallet'
BalanceDetail:
type: object
required:
- type
- activeValue
- activeUnit
description: The details for a balance type.
properties:
type:
type: string
description: This is the type of the value.
enum:
- CURRENCY
- DATA
- MINUTES
- SMS
activeValue:
type: string
description: This is the aggregated formatted active value of a balance type.
example: '136271'
activeUnit:
type: string
description: This is the unit of the aggregated active value.
enum:
- UGX
- ZAR
- NGN
- GB
- MB
- MINUTES
- SMS
Wallet:
type: object
required:
- name
- amount
description: Contributing wallets to the aggregated balance
properties:
name:
type: string
description: The name of a wallet account. E.g. registrationCommission, simswapCommission
example: registrationCommission
amount:
$ref: '#/definitions/Amount'
Amount:
type: object
required:
- value
- type
- unit
description: The amount details for a wallet.
properties:
type:
type: string
description: This is the type of the wallet value.
enum:
- CURRENCY
- DATA
- MINUTES
- SMS
value:
type: string
description: This is the value of a balance wallet.
example: 76923
unit:
type: string
description: This is the unit of the wallet value.
enum:
- UGX
- ZAR
- NGN
- GB
- MB
- MINUTES
- SMS
- FCFA
Devices:
type: object
properties:
data:
type: object
properties:
devices:
type: array
items:
properties:
IMEI:
type: string
description: "Last known IMEI. Unique identifier of Mobile Device used by the MSISDN"
example: "990000862471854"
timePeriods:
type: object
properties:
startDateTime:
type: string
format: date-time
endDateTime:
type: string
format: date-time
ACTIVITYREPORT:
type: object
properties:
firstCallActivationCount:
type: integer
description: 'Number of new customers registered by the agent that have done their first voice call'
example: 110
firstRechargeActivationCount:
type: integer
description: 'Number of new customers registered by the agent that have done their first airtime recharge'
example: 90
agentFLAG:
type: object
properties:
statusCode:
type: string
example: '0000'
message:
type: string
description: 'Response description from the backend system'
example: 'Yello, Requestor should be an agent.'
transactionId:
type: string
description: 'Response Id from the backend'
agentId:
type: string
description: 'ID of the agent. It could be MSISDN, email address, or any other agent identifier. if id is msisdn, format must be E.123'
example: '256789999781'
data:
type: object
properties:
isAgent:
type: boolean
example: false
_links:
allOf:
- description: Links used to access the agent information
- $ref: "#/definitions/AgentLinks"
geoTagging:
type: object
properties:
regLocationLat:
type: number
format: double
description: >-
Latitude value of the place where the agent KYC capture has taken
place
example: 3.225225225225225
regLocationLong:
type: number
format: double
description: >-
Longitude value of the place where the agent KYC capture has
taken place
example: 30.913829549623536
cellGlobalId:
type: string
pattern: '^\d{3}-\d{2}-\d-\w$'
description: Full Cell Global Identity in the format MCC-MNC-LAC-CellId
example: 641-10-2321-6b1c
kycCaptureDateTime:
type: string
format: date-time
description: datetime when the agent KYC capture/update happened, using IETC-RFC-3339 format
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"
installationConfirmationDetailsRequest:
type: "object"
required:
- appCode
- installerCode
- msisdn
- imei
properties:
appCode:
type: string
msisdn:
type: string
imei:
type: string
phoneOSVersion:
type: string
imsi:
type: string
sourceChannel:
type: string
deviceLocation:
type: string
installationConfirmationDetailsResponse:
type: "object"
properties:
statusCode:
type: string
statusMessage:
type: string
timestamp:
type: "string"
format: "date-time"
description: "Error response code"