swagger: "2.0" info: description: |- This API is used to verify/validate SIM Swap status, SIM Activation status and SIM Recycle status of a customer's msisdn. - **'/simSwap/verifyStatus'** capability is used to verify sim swap status as true or false. - **'/simActivation/verifyStatus'** capability is used to verify sim activation status as true or false. - **'/simRecycle/verifyStatus'** capability is used to verify sim recycle status as true or false. - **'/simSwap/validateStatus'** capability is used to validate sim swap status as true or false. - **'/simActivation/validateStatus'** capability is used to validate sim activation status as true or false. - **'/simRecycle/validateStatus'** capability is used to validate sim recycle status as true or false. version: "1.0" title: MTN Customer SIM Verification API host: api.mtn.com basePath: "/v1/simVerification" schemes: - https consumes: - application/json produces: - application/json securityDefinitions: APIKeyAuth: type: apiKey name: x-API-Key in: header OAuth2: type: oauth2 flow: application tokenUrl: 'https://api.mtn.com/oauth/clent_credentials/accesstoken' security: - APIKeyAuth: [] - OAuth2: [] paths: /customers/{customerId}/simSwap/verifyStatus: get: tags: - Sim Swap summary: Verify sim swap status as true or false. description: >- Retrieve sim-swap status indicateing whether a sim swap was performed on a particular msisdn . parameters: - name: customerId in: path description: >- ID of the subscriber is the MSISDN of the subscriber represented as International ITU-T E.164. required: true type: string - name: senderId in: query description: >- Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc. required: true type: string - name: extTransactionId in: header description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: false type: string - name: partnerId in: header description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: true type: string responses: '200': description: Success schema: $ref: '#/definitions/SIMSwapStatus' '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 No Allowed schema: $ref: '#/definitions/Error' '406': description: Not acceptable schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/simSwap/validateStatus: get: tags: - Sim Swap summary: Validate simswap status as true or false. description: >- Validate sim-swap status against the last simswap date supplied by the partner . parameters: - name: customerId in: path description: >- ID of the subscriber is the MSISDN of the subscriber represented as International ITU-T E.164. required: true type: string - name: senderId in: query description: >- Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc. required: true type: string - name: startDate in: query description: >- Start date and end date will be used by 3pp to supply the date range for sim swap (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim swap date required: true type: string - name: endDate in: query description: >- Start date and end date will be used by 3pp to supply the date range for sim swap (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim swap date required: true type: string - name: extTransactionId in: header description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: false type: string - name: partnerId in: header description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: true type: string responses: '200': description: Success schema: $ref: '#/definitions/SIMSwapStatus' '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 No Allowed schema: $ref: '#/definitions/Error' '406': description: Not acceptable schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/simActivation/verifyStatus: get: tags: - Sim Activation summary: Verify sim activation status as true or false. description: >- Retrieve sim-swap status indicateing whether a sim swap was performed on a particular msisdn . parameters: - name: customerId in: path description: >- ID of the subscriber is the MSISDN of the subscriber represented as International ITU-T E.164. required: true type: string - name: senderId in: query description: >- Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc. required: true type: string - name: extTransactionId in: header description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: false type: string - name: partnerId in: header description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: true type: string responses: '200': description: Success schema: $ref: '#/definitions/SIMActivationStatus' '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 No Allowed schema: $ref: '#/definitions/Error' '406': description: Not acceptable schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/simActivation/validateStatus: get: tags: - Sim Activation summary: Validate sim activation status as true or false. description: >- Validate sim activation status against the activation date supplied by the partner . parameters: - name: customerId in: path description: >- ID of the subscriber is the MSISDN of the subscriber represented as International ITU-T E.164. required: true type: string - name: senderId in: query description: >- Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc. required: true type: string - name: startDate in: query description: >- Start date and end date will be used by 3pp to supply the date range for sim activation (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim activation date required: true type: string - name: endDate in: query description: >- Start date and end date will be used by 3pp to supply the date range for sim activation (recent) happened on the customer's msisdn, which will be used by operator to validate against the actual sim activation date required: true type: string - name: extTransactionId in: header description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: false type: string - name: partnerId in: header description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: true type: string responses: '200': description: Success schema: $ref: '#/definitions/SIMActivationStatus' '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 No Allowed schema: $ref: '#/definitions/Error' '406': description: Not acceptable schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' /customers/{customerId}/simRecycle/verifyStatus: get: tags: - Sim Recycle summary: Verify sim recycle status as true or false. description: >- Retrieve sim recycle status indicateing whether a sim swap was performed on a particular msisdn . parameters: - name: customerId in: path description: >- ID of the subscriber is the MSISDN of the subscriber represented as International ITU-T E.164. required: true type: string - name: senderId in: query description: >- Identifier of the request originating system, e.g. 'IVR', 'My MTN App'etc. required: true type: string - name: extTransactionId in: header description: Unique transaction id generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: false type: string - name: partnerId in: header description: Unique identifier generated by source channel for tracing purposes. This field is manadory for MTN-Nigeria. required: true type: string responses: '200': description: Success schema: $ref: '#/definitions/SIMRecycleStatus' '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 No Allowed schema: $ref: '#/definitions/Error' '406': description: Not acceptable schema: $ref: '#/definitions/Error' '500': description: Internal Server Error schema: $ref: '#/definitions/Error' definitions: SIMSwapStatus: $ref: '#/definitions/Status' properties: data: $ref: '#/definitions/SimSwapStatusData' SIMActivationStatus: $ref: '#/definitions/Status' properties: data: $ref: '#/definitions/SimActivationStatusData' SIMRecycleStatus: $ref: '#/definitions/Status' properties: data: $ref: '#/definitions/SimRecycleStatusData' SimSwapStatusData: type: object required: - simSwapSatus properties: simSwapSatus: type: string description: >- Stutus of the swim swap - whether simswap performed (True or False) example: 'True' SimActivationStatusData: type: object required: - simActivationSatus properties: simActivationSatus: type: string description: >- Stutus of the swim activation - whether sim activation performed (True or False) example: 'True' SimRecycleStatusData: type: object required: - simRecycleSatus properties: simRecycleSatus: type: string description: >- Stutus of the swim activation - whether sim activation performed (True or False) example: 'True' Status: required: - customerId - data - statusCode - statusMessage type: object properties: statusCode: type: string description: Status code return to 3PP. It returns '0000' , if request verification/validation holds true example: '0000' statusMessage: type: string description: Status Message. example: Success extTransactionId: type: string description: Transaction ID generated by source system of the request. example: 232TXYZ-212 transactionId: type: string description: Transaction Id generated by MADapi internally example: 2022052510001 customerId: type: string description: MSISDN of the customer provided in the input as customerId example: '256789999781' Error: type: object required: - "statusCode" - "statusMessage" properties: statusCode: type: string description: This is the MADAPI Canonical Error Code (it is 4 characters long and it is not the HTTP Status Code which is 3 characters long). Back-end system errors are mapped to specific canonical error codes which are returned. More information on these mappings can be found on the MADAPI Confluence Page 'Response Codes' example: '1000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client supportMessage: type: string description: Internal message meant for consumers of the API to troubleshoot the error (could possible include the back-end system error code in the message if it would be useful) transactionId: type: string description: This is the same transactionId that is sent in the request timestamp: type: string format: date-time description: Timestamp of the error example: "2019-08-23T07:29:25.593+0000" _links: type: object properties: self: type: object properties: href: type: string example: "https://api.mtn.com/v1/"