swagger: '2.0'
info:
title: Digital Partners Management API
description: >-
TM Forum Open APIs (Apache 2.0) Party Management API
Provides standardized mechanism for digital partner management such as creation, update, retrieval, deletion and notification of events. Partner is an organization that has any kind of relation with the enterprise.
version: '1.0'
host: api.mtn.com
basePath: /digitalPartners/v1
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/json;charset=utf-8
securityDefinitions:
ApiKeyAuth:
type: "apiKey"
name: "X-API-Key"
in: "header"
OAuth2:
type: oauth2
flow: application
tokenUrl: https://api.mtn.com/oauth/client_credential/accesstoken
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: partners
paths:
/partners:
get:
operationId: listOrganization
summary: List or find Organization details
description: This operation list or find Organization entities
tags:
- partners
parameters:
- type: string
required: false
in: header
name: "transactionId"
description: 'Client generated Id to include for tracing requests.'
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- type: string
required: false
in: header
name: "targetSystem"
enum:
- ZSmart
description: 'Provider system name.'
x-example: 'ZSmart'
- type: string
required: false
in: query
name: idType
description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
- type: string
required: false
in: query
name: idValue
description: Value of the 'idType'
- type: string
required: true
in: query
name: customerId
description: This can be msisdn with country code or account number etc.
- type: string
required: false
in: query
name: customerCode
description: Unique id generated for customer.
- type: integer
required: false
in: query
name: offset
description: Requested index for start of resources to be provided in response
- type: integer
required: false
in: query
name: limit
description: Requested number of resources to be provided in response
responses:
'200':
description: Success
headers:
X-Total-Count:
type: integer
description: Total number of items matching criteria
X-Result-Count:
type: integer
description: Actual number of items returned in the response body
schema:
type: object
required:
- result
- data
properties:
result:
$ref: '#/definitions/Result'
data:
type: array
items:
$ref: '#/definitions/Organization'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Customer 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'
post:
operationId: createOrganization
summary: Creates a Organization
description: This operation creates a Organization entity.
tags:
- partners
parameters:
- name: transactionId
type: string
description: "A unique identifier for tracking request/response"
x-example: "32938293823"
in: header
- name: targetSystem
in: header
description: "The target system"
type: string
enum:
- COMVIVA
- schema:
$ref: '#/definitions/Organization_Create'
required: true
in: body
name: organization
description: The Organization to be created
responses:
'201':
description: Created
schema:
type: object
required:
- result
- data
properties:
result:
$ref: '#/definitions/Result'
data:
$ref: '#/definitions/Organization'
#$ref: '#/definitions/Organization'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
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'
'/partners/{id}':
get:
operationId: retrieveOrganization
summary: Retrieves a Organization by ID
description: >-
This operation retrieves a Organization entity. Attribute selection is enabled for all first level attributes.
tags:
- partners
parameters:
- required: true
type: string
name: id
in: path
description: Identifier of the Organization
- type: string
required: false
in: header
name: "transactionId"
description: 'Client generated Id to include for tracing requests.'
x-example: '6f0bece6-7df3-4da4-af02-5e7f16e5e6fc'
- type: string
required: false
in: header
name: "targetSystem"
enum:
- ZSmart
- Comviva
description: 'Provider system name.'
x-example: 'ZSmart'
- name: description
in: query
type: string
description: "Organization description"
- type: string
required: false
in: query
name: idType
description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
- type: string
required: false
in: query
name: idValue
description: Value of the 'idType'
- type: string
required: false
in: query
name: customerCode
description: Unique id generated for customer.
responses:
'200':
description: Success
schema:
type: object
required:
- result
- data
properties:
result:
$ref: '#/definitions/Result'
data:
$ref: '#/definitions/Organization'
'400':
description: Bad Request
schema:
$ref: '#/definitions/Error'
'401':
description: Unauthorized
schema:
$ref: '#/definitions/Error'
'403':
description: Forbidden
schema:
$ref: '#/definitions/Error'
'404':
description: Customer 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'
patch:
operationId: patchOrganization
summary: Updates partially a Organization
description: This operation updates partially a Organization entity.
tags:
- partners
parameters:
- required: true
type: string
name: id
in: path
description: Identifier of the Organization
- required: false
type: string
name: transactionId
in: header
x-example: "88437483748374834738"
- schema:
$ref: '#/definitions/Organization_Update'
required: true
in: body
name: organization
description: The Organization to be updated
responses:
'200':
description: Updated
schema:
type: object
required:
- result
- data
properties:
result:
$ref: '#/definitions/Result'
data:
$ref: '#/definitions/Organization'
'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:
CreateCustomerRequestPayload:
type: object
description: |-
Individual represents a single human being (a man, woman or child). The individual can be a customer, an employee or any other person that the organization needs to store information about.
Skipped properties: id,href
required:
- givenName
- familyName
properties:
id:
type: string
href:
type: string
example: "https://bss-uat.url.co.zm/url/v1/party/PI116984"
reason:
type: string
example: "01"
description:
type: string
example: "A brief description"
aristocraticTitle:
type: string
description: e.g. Baron, Graf, Earl,…
birthDate:
type: string
format: date-time
description: Birth date
countryOfBirth:
type: string
description: Country where the individual was born
deathDate:
type: string
format: date-time
description: Date of death
familyName:
type: string
description: Contains the non-chosen or inherited name. Also known as last name in the Western context
familyNamePrefix:
type: string
description: Family name prefix
formattedName:
type: string
description: A fully formatted name in one string with all of its pieces in their proper place and all of the necessary punctuation. Useful for specific contexts (Chinese, Japanese, Korean,…)
fullName:
type: string
description: Full name flatten (first, middle, and last names)
gender:
type: string
description: Gender
generation:
type: string
description: e.g.. Sr, Jr, III (the third),…
givenName:
type: string
description: First name of the individual
legalName:
type: string
description: Legal name or birth name (name one has for official purposes)
location:
type: string
description: Temporary current location od the individual (may be used if the individual has approved its sharing)
maritalStatus:
type: string
description: Marital status (married, divorced, widow ...)
middleName:
type: string
description: Middles name or initial
nationality:
type: string
description: Nationality
placeOfBirth:
type: string
description: Reference to the place where the individual was born
preferredGivenName:
type: string
description: 'Contains the chosen name by which the individual prefers to be addressed. Note: This name may be a name other than a given name, such as a nickname'
title:
type: string
description: Useful for titles (aristocratic, social,...) Pr, Dr, Sir, ...
contactMedium:
type: array
items:
$ref: '#/definitions/ContactMedium'
creditRating:
type: array
items:
$ref: '#/definitions/PartyCreditProfile'
disability:
type: array
items:
$ref: '#/definitions/Disability'
externalReference:
type: array
items:
$ref: '#/definitions/ExternalReference'
individualIdentification:
type: array
items:
$ref: '#/definitions/IndividualIdentification'
languageAbility:
type: array
items:
$ref: '#/definitions/LanguageAbility'
otherName:
type: array
items:
$ref: '#/definitions/OtherNameIndividual'
partyCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
quote:
type: object
$ref: "#/definitions/QuoteRef"
skill:
type: array
items:
$ref: '#/definitions/Skill'
channel:
$ref: "#/definitions/ChannelRef"
status:
$ref: '#/definitions/IndividualStateType'
description: Status of the individual
recurring:
type: boolean
example: false
recurringCount:
type: number
example: 1
taxExemptionCertificate:
type: array
items:
$ref: '#/definitions/TaxExemptionCertificate'
'@baseType':
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
type: string
description: A URI to a JSON-Schema file that defines additional attributes and relationships
format: uri
'@type':
type: string
description: When sub-classing, this defines the sub-class entity name
ChannelRef:
type: object
description: The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..
properties:
id:
type: string
description: unique identifier
href:
type: string
description: Hyperlink reference
value:
type: string
description: "Value of a particular key"
name:
type: string
description: Name of the channel.
'@baseType':
example: ResourceSpecification
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
QuoteRef:
type: object
description: The channel to which the resource reference to. e.g. channel for selling product offerings, channel for opening a trouble ticket etc..
properties:
id:
type: string
description: unique identifier
href:
type: string
description: Hyperlink reference
value:
$ref: "#/definitions/Any"
name:
type: string
description: Name of the channel.
'@baseType':
example: ResourceSpecification
type: string
description: When sub-classing, this defines the super-class
'@schemaLocation':
example: https://mycsp.com:8080/tmf-api/schema/Resource/LogicalResourceSpecification.schema.json
type: string
format: uri
description: A URI to a JSON-Schema file that defines additional attributes and relationships
'@type':
example: LogicalResourceSpecification
type: string
description: When sub-classing, this defines the sub-class Extensible name
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
Attachment:
type: object
description: >-
Complements the description of an element (for instance a product) through
video, pictures...
properties:
id:
type: string
description: Unique identifier for this particular attachment
href:
type: string
description: URI for this Attachment
attachmentType:
type: string
description: 'Attachment type such as video, picture'
content:
type: string
description: >-
The actual contents of the attachment object, if embedded, encoded as
base64
description:
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: >-
Attachment mime type such as extension file for video, picture and
document
name:
type: string
description: The name of the attachment
url:
type: string
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment is valid
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
AttachmentRef:
type: object
description: >-
Attachment reference. An attachment complements the description of an
element (for instance a product) through video, pictures
properties:
id:
type: string
description: Unique-Identifier for this attachment
href:
type: string
description: URL serving as reference for the attachment resource
description:
type: string
description: A narrative text describing the content of the attachment
name:
type: string
description: Name of the related entity.
url:
type: string
description: Link to the attachment media/content
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
AttachmentRefOrValue:
type: object
description: >-
An attachment by value or by reference. An attachment complements the
description of an element, for example through a document, a video, a
picture.
properties:
id:
type: string
description: Unique identifier for this particular attachment
href:
type: string
description: URI for this Attachment
attachmentType:
type: string
description: 'Attachment type such as video, picture'
content:
type: string
description: >-
The actual contents of the attachment object, if embedded, encoded as
base64
description:
type: string
description: A narrative text describing the content of the attachment
mimeType:
type: string
description: >-
Attachment mime type such as extension file for video, picture and
document
name:
type: string
description: The name of the attachment
url:
type: string
description: 'Uniform Resource Locator, is a web page address (a subset of URI)'
size:
$ref: '#/definitions/Quantity'
description: The size of the attachment.
validFor:
$ref: '#/definitions/TimePeriod'
description: The period of time for which the attachment is valid
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
Characteristic:
type: object
description: >-
Describes a given characteristic of an object or entity through a
name/value pair.
required:
- name
- value
properties:
id:
type: string
description: "Unique identifier"
name:
type: string
description: Name of the characteristic
valueType:
type: string
description: Data type of the value of the characteristic
value:
type: string
description: The value of the characteristic
relatedParty:
type: array
items:
$ref: "#/definitions/RelatedParty"
recurring:
type: boolean
example: false
recurringCount:
type: number
example: 1
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
ContactMedium:
type: object
description: Indicates the contact medium that could be used to contact the party.
properties:
role:
type: string
contactName:
type: string
partyRoleType:
type: string
mediumType:
type: string
description: >-
Type of the contact medium, such as: CONTACT_ADDRESS, DIRECTOR_DETAIL, CONTACT_DETAIL, physicalAdress,postalAddress,contactPerson etc.
verified:
type: boolean
description: "Determines whether the contact details is verified or not"
example: false
preferred:
type: boolean
description: 'If true, indicates that is the preferred contact medium'
characteristic:
$ref: '#/definitions/MediumCharacteristic'
description: Any additional characteristic(s) of this contact medium
validFor:
$ref: '#/definitions/TimePeriod'
description: The time period that the contact medium is valid for
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
Disability:
type: object
description: Lack or inadequate strength or ability.
properties:
disabilityCode:
type: string
description: Code of the disability
disabilityName:
type: string
description: Name of the disability
validFor:
$ref: '#/definitions/TimePeriod'
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
EntityRef:
type: object
description: Entity reference schema to be use for all entityRef class.
properties:
id:
type: string
description: Unique identifier of a related entity.
href:
type: string
description: Reference of the related entity.
name:
type: string
description: Name of the related entity.
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
'@referredType':
type: string
description: The actual type of the target instance when needed for disambiguation.
required:
- id
ExternalReference:
type: object
description: External reference of the individual or reference in other system
properties:
externalReferenceType:
type: string
description: Type of the external reference
name:
type: string
description: External reference name
accountType:
type: string
description: Type of account current or savings, checking etc.
accountName:
type: string
description: Name of account.
accountNumber:
type: string
description: Bank account number.
bankName:
type: string
description: Name ofthe bank where account is domiciled.
branchCode:
type: string
description: Bank branch code.
iban:
type: string
description: Bank iban number.
swiftCode:
type: string
description: Bank swift code.
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defines additional attributes and
relationships
format: uri
'@type':
type: string
description: 'When sub-classing, this defines the sub-class entity name'
Individual:
type: object
description: >-
Individual represents a single human being (a man, woman or child). The individual can be a customer, an employee or any other person that the organization needs to store information about.
required:
- id
properties:
id:
type: string
description: Unique identifier of the individual
href:
type: string
description: Hyperlink to access the individual
reason:
type: string
description:
type: string
aristocraticTitle:
type: string
description: 'e.g. Baron, Graf, Earl,…'
birthDate:
type: string
format: date-time
description: Birth date
countryOfBirth:
type: string
description: Country where the individual was born
deathDate:
type: string
format: date-time
description: Date of death
firstName:
type: string
description: >-
First name of the individual
middleName:
type: string
description: >-
Middle name of the individual
lastName:
type: string
description: >-
Contains the non-chosen or inherited name. Also known as sur name or family name.
familyNamePrefix:
type: string
description: Family name prefix
formattedName:
type: string
description: >-
A fully formatted name in one string with all of its pieces in their
proper place and all of the necessary punctuation. Useful for specific
contexts (Chinese, Japanese, Korean,…)
fullName:
type: string
description: 'Full name flatten (first, middle, and last names)'
gender:
type: string
description: Gender
generation:
type: string
description: 'e.g.. Sr, Jr, III (the third),…'
legalName:
type: string
description: Legal name or birth name (name one has for official purposes)
location:
type: string
description: >-
Temporary current location od the individual (may be used if the
individual has approved its sharing)
maritalStatus:
type: string
description: 'Marital status (married, divorced, widow ...)'
nationality:
type: string
description: Nationality
placeOfBirth:
type: string
description: Reference to the place where the individual was born
preferredGivenName:
type: string
description: >-
Contains the chosen name by which the individual prefers to be
addressed. Note: This name may be a name other than a given name, such as a nickname
title:
type: string
description: 'Useful for titles (aristocratic, social,...) Pr, Dr, Sir, ...'
contactMedium:
type: array
items:
$ref: '#/definitions/ContactMedium'
creditRating:
type: array
items:
$ref: '#/definitions/PartyCreditProfile'
creditRating2:
type: array
items:
$ref: '#/definitions/PartyCreditProfile'
disability:
type: array
items:
$ref: '#/definitions/Disability'
externalReference:
type: array
items:
$ref: '#/definitions/ExternalReference'
individualIdentification:
type: array
items:
$ref: '#/definitions/IndividualIdentification'
languageAbility:
type: array
items:
$ref: '#/definitions/LanguageAbility'
otherName:
type: array
items:
$ref: '#/definitions/OtherNameIndividual'
partyCharacteristic:
type: array
items:
$ref: '#/definitions/Characteristic'
relatedParty:
type: array
items:
$ref: '#/definitions/RelatedParty'
skill:
type: array
items:
$ref: '#/definitions/Skill'
status:
$ref: '#/definitions/IndividualStateType'
description: Status of the individual
taxExemptionCertificate:
type: array
items:
$ref: '#/definitions/TaxExemptionCertificate'
recurring:
type: boolean
example: false
recurringCount:
type: number
example: 1
'@baseType':
type: string
description: 'When sub-classing, this defines the super-class'
'@schemaLocation':
type: string
description: >-
A URI to a JSON-Schema file that defi
# --- truncated at 32 KB (75 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-digital-partner-management.yml