swagger: '2.0' info: description: >- This API to be used to manage a Subscriber information. version: 1.0.2 title: Subscriber Management API host: api.mtn.com basePath: /v1 schemes: - https consumes: - application/json;charset=utf-8 produces: - application/json;charset=utf-8 tags: - name: subscriberinfo securityDefinitions: ApiKeyAuth: type: "apiKey" name: "X-API-Key" in: "header" OAuth2: type: oauth2 flow: application tokenUrl: "https://api.mtn.com/v1/oauth/access_token/accesstoken?grant_type=client_credentials" security: - ApiKeyAuth: [] - OAuth2: [] paths: /subscriber/{id}: get: operationId: retrieveSubscriberinfoById summary: Retrieves a Subscriber info by ID description: >- This operation retrieves a subscriber's detail based upon the filter criteria. tags: - subscriberinfo parameters: - name: id description: Identifier of the subscriber required: true type: string in: path - name: queryType description: "'personalDetail' will return only personal data of the subscriber, i.e., Subscriberinfo object. 'identityDetail' will return only identity information of the subscriber , i.e., SubscriberIdentification object. 'addressDetail' will return only address of the subscriber , i.e., Address object. 'deviceDetail' will return only device related information of the subscriber like puk number , imsi number etc. It will return only SubscriberAsset object in response. 'basicProfile' will return subscriber details , like- subscriber id , subscriber type, subscriber status etc. along with subscriber asset information. 'completeProfile' will return complete information of the subscriber. It will return SubscriberProfile object in response." required: true type: string in: query enum: - personalDetail - identityDetail - addressDetail - deviceDetail - basicProfile - completeProfile default: basicProfile - name: transactionId type: string in: header required: false description: Unique transaction id genereted by client system. This will be used to track requests - name: countryCode type: string in: header required: false description: Will be used internally by application - name: additionalFilter type: string in: query required: false description: "Reserve for future use. This can be used to further filter the response object. For example - if we want to retrieve only username a subscriber, then choose queryType as 'personalDetail' and additionalFilter as 'username'. Use comma seperation if case of retrive multiple attributes of an object" responses: '200': description: Success schema: $ref: '#/definitions/Response_Subscriber' '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' /linkednumber/{id}: get: operationId: retrieveLinkedNumbersById summary: Retrieves MTN numbers linked to an ID description: >- This operation will be used to retrieve the linked numbers associated to an identity, which will be sent to subscriber's msisdn. tags: - subscriberinfo parameters: - name: id description: National ID of a subscriber, which is linked to his/her subscribed MTN numbers. required: true type: string in: path - name: certificateType type: string in: query required: true description: Type of National ID - name: serviceNumber type: string in: query required: true description: MSISDN of the subscriber - name: transactionId type: string in: header required: false description: Unique transaction id genereted by client system. This will be used to track requests - name: countryCode type: string in: header required: false description: Will be used internally by application responses: '200': description: Success schema: $ref: '#/definitions/Response_LinkedNumber' '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: Address: type: object properties: id: type: string description: Unique identifier of the place city: type: string description: City that the address is in country: type: string description: Country that the address is in buildingName: type: string description: allows for buildings that have well-known names levelNumber: type: string description: used where a level type may be repeated e.g. BASEMENT 1, BASEMENT 2 locality: type: string description: >- An area of defined or undefined boundaries within a local authority or other legislatively defined area, usually rural or semi rural in nature. [ANZLIC-STREET], or a suburb, a bounded locality within a city, town or shire principally of urban character [ANZLICSTREET] name: type: string description: >- A user-friendly name for the place, such as [Paris Store], [London Store], [Main Home] postcode: type: string description: >- descriptor for a postal delivery area, used to speed and simplify the delivery of mail (also know as zipcode) stateOrProvince: type: string description: the State or Province that the address is in streetName: type: string description: Name of the street or other street type streetType: type: string description: >- alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf streetLine1: type: string streetLine2: type: string streetLine3: type: string SubscriberIdentification: type: object description: >- Represents our registration of information used as proof of identity by a subscriber (passport, national identity card, drivers license, social security number, birth certificate etc.) properties: identificationId: type: string description: Value of the chosen identification type identificationType: type: string description: >- Identification type (passport, national identity card, drivers license, social security number, birth certificate etc.) issuingAuthority: type: string description: >- Authority which has issued the identifier, such as: social security,town hall etc. issuingDate: type: string format: date description: Date at which the identifier was issued validFor: $ref: '#/definitions/TimePeriod' description: The period for which the identification information is valid. 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 TimePeriod: type: object description: >- A period of time, either as a deadline (endDateTime only) a startDateTime only, or both properties: endDate: example: '1985-04-12' type: string description: 'End of the time period,represented as an [ISO8601-2004] YYYY-MM-DD format' startDate: example: '1985-04-10' type: string format: date description: 'Start of the time period,represented as an [ISO8601-2004] YYYY-MM-DD format' SubscriberAsset: type: object required: - entityType - id properties: id: example: f066ffd5-e685-43bc-ad57-bfb7639decb1 type: string description: >- Unique identifier of referenced entity within the entity/asset pair (customerId, accountId, mobile line number, imsi number, iccid,puk number, pin number ...) assetType: type: string description: >- product/service/resource managed entities (e.g.: mobile line subscription, video platform license, mobile equipment, device information etc). Allows identifying the specific asset within the server referenced. Supported values are implementation and application specific. Other values can be added if those listed are not enough entityType: type: string description: >- Type of managed entity (e.g.: product, resource, service, customer, account) createDate: type: string description : Creation date of the asset resource,represented as an [ISO8601-2004] YYYY-MM-DD format activationDate: type: string description : Activation date of the asset resource,represented as an [ISO8601-2004] YYYY-MM-DD format role: example: owner type: string description: >- Represents the part played by an individual in relation to being granted a set of entitlements for manageable assets (e.g.: owner, user, viewer, ...) Subscriberinfo: type: object required: - name properties: firstName: example: Jane type: string description: >- First name(s) or given name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters middleName: example: Mary type: string description: >- Middle name(s) of the End-User. Note that in some cultures, people can have multiple middle names; all can be present, with the names being separated by space characters. Also note that in some cultures, middle names are not used lastName: example: Doe type: string description: >- Last name(s) or surname(s) or of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters fullName: example: Jane Mary Doe type: string description: >- End-User's full name in displayable form including all name parts, possibly including titles and suffixes, ordered according to the End-User's locale and preferences nickname: example: JaneDoe type: string description: >- Casual name of the End-User that may or may not be the same as the given_name. For instance, a nickname value of Mike might be returned alongside a given_name value of Michael gender: example: female type: string description: >- End-User's gender. Values defined by this specification are female and male. Other values MAY be used when neither of the defined values are applicable birthdate: example: '1970-11-02' type: string description: >- End-User's birthday, represented as an [ISO8601-2004] YYYY-MM-DD format. The year MAY be 0000, indicating that it is omitted. To represent only the year, YYYY format is allowed. Note that depending on the underlying platform's date related function, providing just year can result in varying month and day, so the implementers need to take this factor into account to correctly process the dates email: example: jane.doe@email.com type: string description: >- End-User's preferred e-mail address. Its value MUST conform to the [RFC5322] addr-spec syntax emailVerified: default: false type: boolean description: True if the user's email has been verified. phoneNumber: example: +250897654321 type: string description: >- End-User's preferred mobile number or telephone number. If it's mobile number, format will be mobile number prefixed with country code and (+) sign, for example, +25076854321. [E.164] is RECOMMENDED as the format if it is telephone number, for example, +1 (425) 555-1212 or +56 82) 6872400. If the telephone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678 phoneNumberVerified: default: false type: boolean description: True if the user's phone number has been verified. alternateNumber: example: +250897654543 type: string description: >- End-User's preferred mobile number or telephone number. If it's mobile number, format will be mobile number prefixed with country code and (+) sign, for example, +25076854321. [E.164] is RECOMMENDED as the format if it is telephone number, for example, +1 (425) 555-1212 or +56 82) 6872400. If the telephone number contains an extension, it is RECOMMENDED that the extension be represented using the [RFC3966] extension syntax, for example, +1 (604) 555-1234;ext=5678 preferredLanguage: example: en type: string description: >- End-User's locale, represented as a [RFC5646] language tag. This is typically an [ISO639-1] language code in lowercase and an [ISO3166-1] country code in uppercase, separated by a dash. For example, en-US or fr-CA. As a compatibility note, some implementations have used an underscore as the separator rather than a dash, for example, en_US picture: example: 'https://some.url.com/janeDoe.jpg' type: string description: >- URL of the End-User's profile picture. This URL MUST refer to an image file (for example, a PNG, JPEG, or GIF image file), rather than to a Web page containing an image. Note that this URL SHOULD specifically reference a profile photo of the End-User suitable for displaying when describing the End-User, rather than an arbitrary photo taken by the End-User username: example: janeDoe type: string description: >- User ID of the subscriber profile: example: 'https://my.blog.com/janeDoe' type: string description: >- URL of the End-User's profile page. The contents of this Web page SHOULD be about the End-User website: example: 'https://janedoe.com' type: string description: >- URL of the End-User's Web page or blog. This Web page SHOULD contain information published by the End-User or an organization that the End-User is affiliated with zoneinfo: example: America/Los_Angeles type: string description: >- String from zoneinfo time zone database representing the End-User's time zone. For example, Europe/Paris or America/Los_Angeles Response_Subscriber: type: object required: - resultCode - resultDescription - data 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. data: $ref: '#/definitions/Subscriber' Response_LinkedNumber: 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. data: type: object properties: linkedNumbers: type: array items: type: string Subscriber: type: object properties: subscriberId: type: string description: Subscriber ID subscriberType: type: string description: Subscription type enum: - Prepaid - Postpaid - Hybrid accountNumber: type: string description: Account number of the subscriber serviceNumber: type: string description: Service number of the subscriber. This can be msisdn etc. createDate: type: string description: The date of new connection,represented as an [ISO8601-2004] YYYY-MM-DD format activationDate: type: string description: Activation date of new connection, represented as an [ISO8601-2004] YYYY-MM-DD format validFor: $ref: "#/definitions/TimePeriod" description: Subscription period status: $ref : "#/definitions/StatusType" description: type: string description: Blocking description etc. effectiveDate: type: string description: Effective date of blocking or termination etc, represented as an [ISO8601-2004] YYYY-MM-DD format personalDetail: $ref: "#/definitions/Subscriberinfo" addressDetail: $ref: "#/definitions/Address" identificationDetail: type: array items: $ref : "#/definitions/SubscriberIdentification" assetDetail: type: array items: $ref : "#/definitions/SubscriberAsset" StatusType: type: string enum: - Active - Inactive - One-Way Block - Two-Way Block - Termination Error: type: "object" title: "Error" required: - "status" - "message" properties: timestamp: type: "string" format: "date-time" description: "Time stamp of the error" status: type: "string" description: "Status/Error code returned from the provider system" error: type: "string" description: "Status/Error description" message: type: "string" description: "More error details and corrective measures" path: type: "string" description: "the path that caused the error"