openapi: 3.2.0 info: version: v1.0.1 title: MTN Customer Score Reporting API description: This API is used to determine the customer's score through an activities performed within a period of time. servers: - url: https://api.mtn.com/v1 tags: - name: Reporting paths: /customers/{customerId}/score/creditreport: get: operationId: retrieve credit score report summary: retrieve credit score report for an individual and coorporate entity description: This operation retrieves a credit score report for an individual and coorporate entity. This can be a nano, classic or a basic individual or cooporate report tags: - Reporting parameters: - required: true name: customerId in: path description: Identifier of the Individual. This could be msisdn number with country code or an organisation business ID for a corporate report 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: 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 - 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 - name: customerCode required: false in: query schema: type: string - required: false in: query name: calllbackUrl description: URL that will receive final results for async processing schema: type: string - name: referenceNumber in: query description: Reference number that is used when merging multiple facilities schema: type: string - name: facilityId in: query schema: type: string - name: facilityList description: This is a comma separated list of the different failities to be merged in: query schema: type: array items: type: string - name: requestType description: identifier to know if the request is for an individual, corporate or a merge request in: query schema: type: string enum: - individual - corporate - merge_request responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ScoreReportResponse' '201': description: Accepted content: application/json: schema: description: The request has been accepted for processing, but the processing has not been completed. properties: statusCode: type: string description: HTTP error code extension example: '0000' statusMessage: type: string description: Status codoe description example: Request has been received and you will receive results on the callback URL transactionId: type: string example: MTN123456 description: Id provided in the input _links: type: object properties: self: type: object properties: href: type: string example: https://api.mtn.com/v1/customers/2348076891321/credit-report '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Customer Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '405': description: Method Not allowed content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Error' '415': description: Unsupported Media Type content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ScoreReportResponse: type: object 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: '0000' statusMessage: type: string description: More details and corrective actions related to the error which can be shown to a client transactionId: type: string description: This is the same transactionId that is sent in the request sequenceNo: type: string description: This is the MADAPI auto generated reference for tracing purposes data: $ref: '#/components/schemas/ReportData' ReportData: type: object properties: referenceNumber: type: string description: This is the consumer reference number that is is returned when multiple facilities are returned AddressHistory: type: array items: type: object properties: ADDRESS: type: string ADDR_TYPE: type: string DATE_REPORTED: type: string SNO: type: string Amount_OD_BucketCURR1: type: object properties: Amount_OD_BucketCURR1: type: array items: type: object properties: Apr19: type: string format: nullable Aug19: type: string format: nullable Jul19: type: string format: nullable Jun19: type: string format: nullable May19: type: string format: nullable Sep19: type: string format: nullable TYPE: type: string Credit_Utilization_TrendCURR1: type: array items: type: object properties: Type: type: string Values: type: integer format: int32 Amount_OD_BucketCURR2: type: object Amount_OD_BucketCURR3: type: object Amount_OD_BucketCURR4: type: object Amount_OD_BucketCURR5: type: object CONSUMER_RELATION: type: string format: nullable CREDIT_MICRO_SUMMARY: type: object format: nullable properties: CURRENCY: type: object properties: BUREAU_CURRENCY: type: string CURRENCY_CODE: type: string DUESUMMARY: type: array items: $ref: '#/components/schemas/SummaryOverdue' LAST_REPORTED_DATE: type: string example: 30-APR-2021 REPORTDATE: type: object properties: BUREAU_CURRENCY: type: string example: NGN LAST_REPORTED_DATE: type: string example: 30-APR-2021 SUMMARY: type: array items: $ref: '#/components/schemas/Summary' CREDIT_NANO_SUMMARY: type: string format: nullable CREDIT_SCORE_DETAILS: type: object properties: CREDIT_SCORE_SUMMARY: type: object properties: CREDIT_RATING: type: string CREDIT_SCORE: type: integer format: int32 REASON_CODE1: type: string REASON_CODE2: type: string REASON_CODE3: type: string REASON_CODE4: type: string ClassificationInsType: type: array items: type: object properties: AMOUNT_OVERDUE: type: string APPROVED_CREDIT_SANCTIONED: type: string CURRENCY: type: string ClassificationInsType: type: string format: nullable INSTITUTION_TYPE: type: string LEGAL_FLAG: type: string NO_OF_ACCOUNTS: type: string OUSTANDING_BALANCE: type: string ClassificationProdType: type: array items: type: object properties: AMOUNT_OVERDUE: type: string CURRENCY: type: string ClassificationProdType: type: string format: nullable NO_ACC_LAST_SIX_MON: type: string NO_OF_ACCOUNTS: type: string PRODUCT_TYPE: type: string RECENT_OVERDUE_DATE: type: string format: nullable SANCTIONED_AMOUNT: type: string TOTAL_OUTSTANDING_BALANCE: type: string ClosedAccounts: type: object properties: ClosedAccounts: type: object properties: ACCOUNT_STATUS: type: string CF_CLOSING_DATE: type: string CREDIT_FACILITY_TYPE: type: string CURRENCY: type: string INSTITUTION_NAME: type: string LEGAL_ACTION_STATUS: type: string SANCTION_AMOUNT: type: string SNO: type: string ConsCommDetails: type: object properties: ConsCommDetails_ID: type: array items: type: object properties: EXPIRY_DATE: type: string format: nullable IDENTIFIERNUMBER: type: string IDENTIFIER_NUMBER: type: string ID_TYPE: type: string ConsCommDetails_Subject: type: object properties: ADDRESS: type: string APPLICATIONVIABILITYSCORE: type: string DATE_OF_BIRTH: type: string DATE_OF_BIRTH_M: type: string format: date GENDER: type: string NAME: type: string NATIONALITY: type: string PHONE_NO1: type: string PHONE_NO2: type: string ConsumerMergerDetails: type: object properties: ConsumerMergerDetails: type: object format: nullable properties: DATE_OF_REGISTRATION: type: string DOR: type: string example: 01-Jan-1991 NAME: type: string example: HEAD OF SERVICE PAYMENT OF OUTST PRIORITY: type: string example: Primary SN: type: integer example: 1 ContactHistory: type: array items: type: object properties: CONTACT_TYPE: type: string DATE_REPORTED: type: string DETAILS: type: string SNO: type: string CreditDisputeDetails: type: object format: nullable ExposureRelatedCompanies: type: object properties: ExposureRelatedCompanies: type: object format: nullable CreditFacilityHistory24: type: array items: type: object properties: ACCOUNT_NUMBER: type: string ACC_OPEN_DISB_DT: type: string AMOUNT_OVERDUE_CAL: type: string AMOUNT_WRITTEN_OFF: type: object ASSET_CLASSIFICATION_CAL: type: string CURRENCY: type: string CURRENCY_VALUE: type: string CURRENT_BALANCE_CAL: type: string DATE_REPORTED: type: string format: date-time DATE_REPORTED_AGE: type: string DPD120: type: object DPD150: type: object DPD180: type: object DPD180P: type: object DPD30: type: object DPD60: type: object DPD90: type: object EXPECT_NXT_INSTALLMENT_AMT: type: object ExposureGuarantors: type: string format: nullable IFF_TYPE: type: string INSTITUTION_NAME: type: string LASTREPAYAMT_DT_CAL: type: string LOAN_STATUS: type: string LOAN_TYPE: type: string LOAN_TYPE_VALUE: type: string MATURITY_DT: type: string MONTH1: type: string example: OK MONTH10: type: string example: OK MONTH11: type: string example: OK MONTH12: type: string example: OK MONTH13: type: string example: OK MONTH14: type: string example: OK MONTH15: type: string example: OK MONTH16: type: string example: OK MONTH17: type: string example: OK MONTH18: type: string example: OK MONTH19: type: string example: OK MONTH2: type: string example: OK MONTH20: type: string example: OK MONTH21: type: string example: OK MONTH22: type: string example: OK MONTH23: type: string example: OK MONTH24: type: string example: OK MONTH3: type: string example: OK MONTH4: type: string example: OK MONTH5: type: string example: OK MONTH6: type: string example: OK MONTH7: type: string example: OK MONTH8: type: string example: OK MONTH9: type: string example: OK MONTH_1: type: string example: Apr-21 MONTH_10: type: string MONTH_11: type: string MONTH_12: type: string MONTH_13: type: string MONTH_14: type: string MONTH_15: type: string MONTH_16: type: string MONTH_17: type: string MONTH_18: type: string MONTH_19: type: string MONTH_2: type: string MONTH_20: type: string MONTH_21: type: string MONTH_22: type: string MONTH_23: type: string MONTH_24: type: string MONTH_3: type: string MONTH_4: type: string MONTH_5: type: string MONTH_6: type: string MONTH_7: type: string MONTH_8: type: string MONTH_9: type: string NUMBER_OF_INSTALLMENTS: type: string NUM_OF_DAYS_IN_ARREARS_CAL: type: string OWNERSHIP_INDICATOR: type: string RANKING: type: string REASON_CODE: type: string REASON_CODE_VALUE: type: string REPAYMENT_FREQUENCY: type: string REPORTED_DT_TEXT: type: string RESTRUCTREASON: type: object RESTRUCT_DT: type: object SANCTIONED_AMOUNT_CAL: type: string SECURITY_COVERAGE: type: string SECURITY_VALUE: type: string SIN: type: string SNO: type: string S_NO: type: string TYPE: type: string TYPE_Basic_RPT: type: string UNIQUE_ROOT_ID: type: string CreditProfileOverview: type: array items: type: object properties: INDICATOR: type: string INDICATOR_TYPE: type: string VALUE: type: string CreditProfileSummaryCURR1: type: array items: type: object properties: Apr19: type: string format: nullable Aug19: type: string format: nullable Jul19: type: string format: nullable Jun19: type: string format: nullable May19: type: string format: nullable Sep19: type: string format: nullable TYPE: type: string CreditProfileSummaryCURR2: type: array items: type: object CreditProfileSummaryCURR3: type: array items: type: object CreditProfileSummaryCURR4: type: array items: type: object CreditProfileSummaryCURR5: type: array items: type: object DMMDisputeSection: type: object properties: DMMDisputeSection: type: string format: nullable DODishonoredChequeDetails: type: array items: type: object DOJointHolderDetails: type: object properties: DOJointHolderDetails: type: string format: nullable DOLitigationDetails: type: array items: type: object DisclaimerDetails: type: object EmploymentHistory: type: object properties: EmploymentHistory: type: object properties: ADDRESS: type: string format: nullable DATE_REPORTED: type: string EMPLOYER_NAME: type: string format: nullable EMP_EXP_MONTH: type: string format: nullable POSITION: type: string format: nullable SNO: type: string GuaranteedLoanDetails: type: array items: type: object InquiryHistoryDetails: type: array items: type: object properties: FACILITY_TYPE: type: string INQUIRY_DATE: type: string INSTITUTION_TYPE: type: string SNO: type: string Inquiry_Product: type: array items: type: object properties: BANK: type: string MICRO: type: string MORTGAGE: type: string NBFC: type: string OTHER: type: string PRODUCT_TYPE: type: string TOTAL: type: string LegendDetails: type: object MFCREDIT_MICRO_SUMMARY: type: string format: nullable MFCREDIT_NANO_SUMMARY: type: string format: nullable MGCREDIT_MICRO_SUMMARY: type: string format: nullable MGCREDIT_NANO_SUMMARY: type: string format: nullable MIC_CONSUMER_PROFILE: type: string format: nullable NANO_CONSUMER_PROFILE: type: string format: nullable RelatedToDetails: type: object properties: RelatedToDetails: type: string format: nullable ReportDetail: type: object properties: ReportDetailBVN: type: string format: nullable ReportDetailAcc: type: object properties: ReportDetailAcc: type: string format: nullable ReportDetailBVN: type: object properties: ReportDetailBVN: type: object properties: BVN_NUMBER: type: integer format: int64 CIR_NUMBER: type: string DATE_OF_BIRTH: type: string format: nullable DATE_OF_BIRTH_M: type: string format: nullable GENDER: type: string format: nullable INSTITUTION_NAME: type: string NAME: type: string format: nullable REPORT_ORDER_DATE: type: string REPORT_ORDER_DATE_M: type: string format: nullable SEARCH_CONFIDENCE_SCORE: type: string ReportDetailMob: type: object properties: ReportDetailMob: type: string format: nullable ReportDetailsSIR: type: object SecurityDetails: type: array items: type: object SummaryOfPerformance: type: array items: type: object properties: ACCOUNT_BALANCE: type: string APPROVED_AMOUNT: type: string DATA_PRDR_ID: type: string DISHONORED_CHEQUES_COUNT: type: string FACILITIES_COUNT: type: string INSTITUTION_NAME: type: string NONPERFORMING_FACILITY: type: string OVERDUE_AMOUNT: type: string PERFORMING_FACILITY: type: string HEADER: type: object properties: REPORTHEADER: type: object properties: MAILTO: type: string PRODUCTNAME: type: string REASON: type: object REPORTDATE: type: string REPORTORDERNUMBER: type: string USERID: type: string RESPONSETYPE: type: object properties: CODE: type: string DESCRIPTION: type: string SEARCHCRITERIA: type: object properties: BRANCHCODE: type: string format: nullable BVN_NO: type: string CFACCOUNTNUMBER: type: string format: nullable DATEOFBIRTH: type: string format: nullable GENDER: type: string format: nullable NAME: type: string format: nullable TELEPHONE_NO: type: string format: nullable SEARCHRESULTLIST: type: object properties: SEARCHRESULTITEM: type: object properties: ADDRESSES: type: object BUREAUID: type: string CONFIDENCESCORE: type: string IDENTIFIERS: type: object NAME: type: string SURROGATES: type: object REQUESTID: type: string Summary: type: object properties: BUREAU_CURRENCY: type: string example: NGN HEADINGTEXT: type: string NO_OF_OPENEDCREDITFACILITIES: type: string OWNERSHIP_TYPE: type: string SANCTIONED_AMOUNT: type: string NO_OF_OPENEDCREDITFACILITIESSpecified: type: boolean TOTAL_NO_OF_CREDITFACILITIES: type: string TOTAL_NO_OF_CREDITGRANTORS: type: string TOTAL_OUTSTANDING: type: string SummaryOverdue: type: object properties: BUREAU_CURRENCY: type: string example: NGN HEADINGTEXT: type: string MAX_NUM_DAYS_DUE: type: string NO_OF_DELINQCREDITFACILITIES: type: string NO_OF_DELINQCREDITFACILITIESSpecified: type: boolean OWNERSHIP_TYPE: type: string TOT_DUE: type: string TOT_DUESpecified: type: boolean 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 that the error occurred example: 2020-08-01T12:34 sequenceNo: type: string description: This is the MADAPI auto generated reference for tracing purposes _links: type: object properties: self: type: object properties: href: type: string example: https://api.mtn.com/v1/customers/2348024008124/score securitySchemes: ApiKeyAuth: type: apiKey name: X-API-Key in: header