MTN Group Individual API

openapi: 3.2.0
info:
  title: Mtn Group Individual API
  version: '1.0'
  description: 'Operations tagged individual across 2 of this provider''s published API definitions: mtn-group-mtn-party-management.yml, mtn-group-rwanda-party-management.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.mtn.com/party/v1
security:
- ApiKeyAuth: []
- OAuth2: []
tags:
- name: individual
paths:
  /individual:
    get:
      operationId: listIndividual
      summary: List or find Individual details
      description: This operation list or find Individual entities
      tags:
      - individual
      parameters:
      - required: false
        in: header
        name: transactionId
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - required: false
        in: header
        name: targetSystem
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
      - required: true
        in: query
        name: countryCode
        description: Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)
        schema:
          type: string
          enum:
          - NGA
          - UGA
          - ZAF
          - RWA
          - ZMB
          - GHN
      - required: false
        in: query
        name: idType
        description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
        schema:
          type: string
      - required: false
        in: query
        name: idValue
        description: Value of the 'idType
        schema:
          type: string
      - required: true
        in: query
        name: customerId
        description: This can be msisdn with country code or account number etc.
        schema:
          type: string
      - required: false
        in: query
        name: customerCode
        description: Unique id generated for customer.
        schema:
          type: string
      - required: false
        in: query
        name: offset
        description: Requested index for start of resources to be provided in response
        schema:
          type: integer
      - required: false
        in: query
        name: limit
        description: Requested number of resources to be provided in response
        schema:
          type: integer
      responses:
        '200':
          description: Success
          headers:
            X-Total-Count:
              description: Total number of items matching criteria
              schema:
                type: integer
            X-Result-Count:
              description: Actual number of items returned in the response body
              schema:
                type: integer
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Individual'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.mtn.com/party/v1
  /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
        name: id
        in: path
        description: Identifier of the Individual. This could be msisdn number with country code or customer ID of the subscriber
        schema:
          type: string
      - required: false
        in: header
        name: transactionId
        description: Client generated Id to include for tracing requests.
        x-example: 6f0bece6-7df3-4da4-af02-5e7f16e5e6fc
        schema:
          type: string
      - required: false
        in: header
        name: targetSystem
        description: Provider system name.
        x-example: ZSmart
        schema:
          type: string
          enum:
          - ZSmart
      - required: true
        in: query
        name: countryCode
        description: Country ISO code. Must be ISO 3166-1 alpha-3 codes (It is a 3 character string)
        schema:
          type: string
          enum:
          - NGA
          - UGA
          - ZAF
          - RWA
          - ZMB
          - GHN
      - required: false
        in: query
        name: idType
        description: This should be the type of ID. For eaxmple- passport, national identity card,refugee under document etc.
        schema:
          type: string
      - required: false
        in: query
        name: idValue
        description: Value of the 'idType'
        schema:
          type: string
      - required: false
        in: query
        name: customerCode
        description: Unique id generated for customer
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json;charset=utf-8:
              schema:
                type: object
                required:
                - result
                - data
                properties:
                  result:
                    $ref: '#/components/schemas/Result'
                  data:
                    $ref: '#/components/schemas/Individual'
        '400':
          description: Bad Request
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Customer Not Found
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '405':
          description: Method Not allowed
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json;charset=utf-8:
              schema:
                $ref: '#/components/schemas/Error'
    servers:
    - url: https://api.mtn.com/party/v1
components:
  schemas:
    IndividualStateType:
      type: string
      description: Valid values for the lifecycle state of the individual
      enum:
      - initialized
      - validated
      - deceaded
    RelatedParty:
      type: object
      description: Related Entity reference. A related party defines party or party role linked to a specific entity.
      required:
      - '@referredType'
      - id
      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.
        role:
          type: string
          description: Role played by the related party
        '@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.
    IndividualIdentification:
      type: object
      description: Represents our registration of information used as proof of identity by an individual (passport, national identity card, drivers license, social security number, birth certificate)
      properties:
        identificationId:
          type: string
          description: Identifier
        identificationType:
          type: string
          description: Identification type (passport, national identity card, drivers license, social security number, birth certificate)
        issuingAuthority:
          type: string
          description: Authority which has issued the identifier, such as 'social security','town hall' etc.
        issuingCountry:
          type: string
          description: Country which has issued the identifier
        issuingDate:
          type: string
          format: date-time
          description: Date at which the identifier was issued
        expiryDate:
          type: string
          format: date-time
          description: Date till which the identifier will be valid
        attachment:
          $ref: '#/components/schemas/AttachmentRefOrValue'
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The period for which the identification information 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
    LanguageAbility:
      type: object
      description: Ability of an individual to understand or converse in a language.
      properties:
        isFavouriteLanguage:
          type: boolean
          description: A “true” value specifies whether the language is considered by the individual as his favourite one
        languageCode:
          type: string
          description: Language code (RFC 5646)
        languageName:
          type: string
          description: Language name
        listeningProficiency:
          type: string
          description: Listening proficiency evaluated for this language
        readingProficiency:
          type: string
          description: Reading proficiency evaluated for this language
        speakingProficiency:
          type: string
          description: Speaking proficiency evaluated for this language
        writingProficiency:
          type: string
          description: Writing proficiency evaluated for this language
        validFor:
          $ref: '#/components/schemas/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
    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: '#/components/schemas/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
    Result:
      type: object
      required:
      - resultCode
      - resultDescription
      properties:
        resultCode:
          type: string
          description: Result code. Example- '0000'
        resultDescription:
          type: string
          description: Result message. Example- 'Successfully processed'
        transactionId:
          type: string
          description: Transaction id returned by the provider system.
    PartyCreditProfile:
      type: object
      description: An individual might be evaluated for its worthiness and this evaluation might be based on a credit rating given by a credit agency.
      properties:
        creditAgencyName:
          type: string
          description: Name of the credit agency giving the score
        creditAgencyType:
          type: string
          description: Type of the credit agency giving the score
        ratingReference:
          type: string
          description: Reference corresponding to the credit rating
        ratingScore:
          type: integer
          description: A measure of a party’s creditworthiness calculated on the basis of a combination of factors such as their income and credit history
        validFor:
          $ref: '#/components/schemas/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
    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: '#/components/schemas/Quantity'
          description: The size of the attachment.
        validFor:
          $ref: '#/components/schemas/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.
    MediumCharacteristic:
      type: object
      description: Describes the contact medium characteristics that could be used to contact a party (an individual or an organization)
      properties:
        city:
          type: string
          description: The city
        contactType:
          type: string
          description: 'The type of contact, for example: phone number such as mobile, fixed home, fixed office. postal address such as shipping instalation…'
        addressType:
          type: string
          description: Type of address such as residential address, office address etc.
        placeName:
          type: string
          description: Name of village or town or place etc.
        sectorName:
          type: string
          description: Name of sector or relevant etc.
        cellName:
          type: string
          description: Name of cell number or town or place etc.
        districtName:
          type: string
          description: Name of village or town or place etc.
        street1:
          type: string
          description: Describes the street
        street2:
          type: string
        postCode:
          type: string
          description: Postcode
        stateOrProvince:
          type: string
          description: State or province
        country:
          type: string
          description: The country
        emailAddress:
          type: string
          description: Full email address in standard format
        faxNumber:
          type: string
          description: The fax number of the contact
        phoneNumber:
          type: string
          description: The primary phone number of the contact
        alternateNumber:
          type: array
          items:
            type: string
            description: List of alternate phone/contact numbers of the customer
            example:
            - '2507865432'
            - '2507235432'
            - '2507234232'
        socialNetworkId:
          type: string
          description: Identifier as a member of a social network
        '@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: '#/components/schemas/ContactMedium'
        creditRating:
          type: array
          items:
            $ref: '#/components/schemas/PartyCreditProfile'
        disability:
          type: array
          items:
            $ref: '#/components/schemas/Disability'
        externalReference:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReference'
        individualIdentification:
          type: array
          items:
            $ref: '#/components/schemas/IndividualIdentification'
        languageAbility:
          type: array
          items:
            $ref: '#/components/schemas/LanguageAbility'
        otherName:
          type: array
          items:
            $ref: '#/components/schemas/OtherNameIndividual'
        partyCharacteristic:
          type: array
          items:
            $ref: '#/components/schemas/Characteristic'
        relatedParty:
          type: array
          items:
            $ref: '#/components/schemas/RelatedParty'
        skill:
          type: array
          items:
            $ref: '#/components/schemas/Skill'
        status:
          $ref: '#/components/schemas/IndividualStateType'
          description: Status of the individual
        taxExemptionCertificate:
          type: array
          items:
            $ref: '#/components/schemas/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
    Error:
      type: object
      title: Error
      required:
      - status
      - message
      properties:
        timestamp:
          type: string
          format: date-time
          description: Error response code
        status:
          type: string
          description: HTTP Status code
        error:
          type: string
          description: Status description
        message:
          type: string
          description: More error details and corrective measures
        path:
          type: string
          description: the path that caused the error
    Skill:
      type: object
      description: 'Skills evaluated for an individual with a level and possibly with a limited validity when an obsolescence is defined (Ex: the first-aid certificate first level is limited to one year and an update training is required each year to keep the level).'
      properties:
        comment:
          type: string
          description: A free text comment linked to the evaluation done
        evaluatedLevel:
          type: string
          description: Level of expertise in a skill evaluated for an individual
        skillCode:
          type: string
          description: Code of the skill
        skillName:
          type: string
          description: Name of the skill such as Java language,…
        validFor:
          $ref: '#/components/schemas/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
    TaxDefinition:
      type: object
      description: Reference of a tax definition. A tax is levied by an authorized tax jurisdiction. There are many different types of tax (Federal Tax levied by the US Government, State Tax levied by the State of California,…).
      properties:
        id:
          type: string
          description: Unique identifier of the tax.
        name:
          type: string
          description: Tax name.
        taxType:
          type: string
          description: Type of  the tax.
        '@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.
    TimePeriod:
      type: object
      description: A period of time, either as a deadline (endDateTime only) a startDateTime only, or both
      properties:
        endDateTime:
          type: string
          format: date-time
          description: End of the time period, using IETC-RFC-3339 format
        startDateTime:
          type: string
          format: date-time
          description: Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end
    OtherNameIndividual:
      type: object
      description: Keeps track of other names, for example the old name of a woman before marriage or an artist name.
      properties:
        aristocraticTitle:
          type: string
          description: e.g. Baron, Graf, Earl,…
        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)
        generation:
          type: string
          description: e.g. Sr, Jr…
        givenName:
          type: string
          description: First name
        legalName:
          type: string
          description: Legal name or birth name (name one has for official purposes)
        middleName:
          type: string
          description: Middle name or initial
        preferredGivenName:
          type: string
          description: 'Contains the chosen name by which the person prefers to be addressed. Note: This name may be a name other than a given name, such as a nickname'
        title:
          type: string
          description: 'Use for titles (aristrocatic, social, ...): Pr, Dr, Sir,....'
        validFor:
          $ref: '#/components/schemas/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
    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
    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
    Quantity:
      type: object
      description: An amount in a given unit
      properties:
        amount:
          default: 1
          type: number
          format: float
          description: Numeric value in a given unit
        units:
          type: string
          description: Unit
    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: '#/components/schemas/MediumCharacteristic'
          description: Any additional characteristic(s) of this contact medium
        validFor:
          $ref: '#/components/schemas/TimePeriod'
          description: The time period that the contact medium is valid for
        '@baseType':
          type: string
          description: When sub-classing, this 

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/mtn-group/refs/heads/main/openapi/mtn-group-individual-api-openapi.yml