This API provides standardized mechanism for party management such as creation, update, retrieval and deletion of a party. Party can be an individual or an organization that has any kind of relation with the enterprise.
swagger: '2.0'
info:
title: Party Management API
description: This API provides standardized mechanism for party management such as creation, update, retrieval and deletion of a party. Party can be an individual or an organization that has any kind of relation with the enterprise.
version: '1.0'
host: api.mtn.com
basePath: /party/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: individual
- name: organization
paths:
/individual:
get:
operationId: listIndividual
summary: List or find Individual details
description: This operation list or find Individual entities
tags:
- individual
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: true
in: query
name: countryCode
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
enum:
- "NGA"
- "UGA"
- "ZAF"
- "RWA"
- "ZMB"
- "GHN"
- 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/Individual'
'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'
'/individual/{id}':
get:
operationId: retrieveIndividual
summary: Retrieves a Individual by ID
description: >-
This operation retrieves a Individual entity. Attribute selection is enabled for all first level attributes.
tags:
- individual
parameters:
- required: true
type: string
name: id
in: path
description: Identifier of the Individual. This could be msisdn number with country code or customer ID of the subscriber
- 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: true
in: query
name: countryCode
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
enum:
- "NGA"
- "UGA"
- "ZAF"
- "RWA"
- "ZMB"
- "GHN"
- 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/Individual'
'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'
/organization:
get:
operationId: listOrganization
summary: List or find Organization details
description: This operation list or find Organization entities
tags:
- organization
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: true
in: query
name: countryCode
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
enum:
- "NGA"
- "UGA"
- "ZAF"
- "RWA"
- "ZMB"
- "GHN"
- 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'
'/organization/{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:
- organization
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
description: 'Provider system name.'
x-example: 'ZSmart'
- type: string
required: true
in: query
name: countryCode
description: "Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)"
enum:
- "NGA"
- "UGA"
- "ZAF"
- "RWA"
- "ZMB"
- "GHN"
- 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'
definitions:
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:
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
'@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:
mediumType:
type: string
description: >-
Type of the contact medium, such as: physicalAdress,postalAddress,contactPerson etc.
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
'@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
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'
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'
'@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_Create:
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:
- id
- givenName
- familyName
properties:
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'
skill:
type: array
items:
$ref: '#/definitions/Skill'
status:
$ref: '#/definitions/IndividualStateType'
description: Status of the individual
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'
Individual_Update:
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:
- id
properties:
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
desc
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-rwanda-party-management.yml