> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria/credit-services/credit-history.md). # Credit History See the **credit history** of a person in the **credit bureaus of Nigeria** based on their BVN and returns the holder's credit profile, including the **loan summary** and their performance. ### Endpoint ``` POST /kyc/nga/credit-history/{provider} ``` ### Authentication | Type | Location | Name | | ------- | -------- | ------------- | | API Key | Header | **x-api-key** | ### Path parameters | Parameter | Type | Required | Description | | ---------- | ------ | -------- | -------------------------------------------------------------------------------------- | | `provider` | string | **Yes** | Credit bureau to query. Possible values: `crc`, `xds`, `all` (query **both** bureaus). | ### Request body **Content-Type:** `application/json` #### Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | -------------------------------------------------------- | | `bvn` | string | **Yes** | Bank Verification Number of **11 digits** of the holder. | #### Request example ``` POST /kyc/nga/credit-history/all ``` ```json { "bvn": "12345678901" } ``` ### Responses #### `200` Success #### Response parameters | Parameter | Type | Description | | ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------ | | `serviceResultCode` | integer | Code that indicates the **overall result** of the service execution. See [Service Result Code](#service-result-code) | | `serviceTime` | string | Processing time **(milliseconds)**. | | `serviceResultLog` | string | Descriptive field for the result of the service execution. Includes details when there is an error or exception in the module. | | `serviceTransactionId` | string | Transaction identifier associated with the request processed by the API. | | `data` | object | Object with the holder's credit profile. See the table below. | #### Response parameters — `data` **Note:** the object `data` is returned **without field mapping or normalization**. The holder's profile and credit history are **unique** (consolidated), not one block per bureau. | Parameter | Type | Description | | ---------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `providers` | array | List of **bureaus that returned information**, as an array of strings. Possible values: `crc`, `xds`. When querying a single bureau, it contains only that value. | | `profile` | object | **Holder profile** (unique). See the table below. | | `credit_history` | array | **Credit history** grouped by financial institution. See the table below. | #### Response parameters — `profile` | Parameter | Type | Description | | ----------------- | ------ | -------------------------------------------------------------------------------------------------------- | | `full_name` | string | Holder's full name. | | `date_of_birth` | string | Date of birth. | | `gender` | string | Gender, in lowercase. E.g.: `male`, `female` | | `address_history` | array | Reported addresses. Each element contains `address`, `type` and `date_reported`. | | `email_address` | array | Registered email addresses (array of strings). | | `phone_number` | array | Registered phone numbers (array of strings). | | `identifications` | array | Holder's identifications. Each element contains `do` (number) and `type` (e.g.: `BVN`, `NIN`, `PENCOM`). | #### Response parameters — `credit_history[]` | Parameter | Type | Description | | ------------- | ------ | --------------------------------------------------------------- | | `institution` | string | Financial institution that reported the loans. | | `history` | array | List of loans reported by the institution. See the table below. | #### Response parameters — `history[]` | Parameter | Type | Description | | --------------------- | ------ | -------------------------------------------------------------- | | `date_opened` | string | Loan opening date. | | `closed_date` | string | Loan closing date. | | `currency` | string | Loan currency. E.g.: `NGN` | | `institution` | string | Financial institution (repeated within each loan). | | `loan_status` | string | Loan status. E.g.: `open`, `closed` | | `opening_balance` | number | Loan opening amount. | | `performance_status` | string | Loan performance. E.g.: `performing` | | `repayment_amount` | number | Repayment installment amount. | | `repayment_frequency` | string | Repayment frequency. E.g.: `monthly` | | `repayment_schedule` | array | Repayment schedule. Each element contains `date` and `status`. | | `tenor` | number | Loan term (in months). | #### Service Result Code The `serviceResultCode` indicates the overall result of the service execution and reflects the **HTTP status code** of the response: | serviceResultCode | Description | HTTP code | | ----------------- | --------------------------------------------------------------------------------- | --------- | | 200 | The service execution was successful, the module processed the request correctly. | 200 | #### Response example ```json { "serviceResultCode": 200, "serviceTime": "2400", "serviceResultLog": "Success", "serviceTransactionId": "e41h235i-34i2-1h3l-h86h-2i681hj22jk", "data": { "credit_history": [ { "institution": "GUARANTY TRUST BANK PLC", "history": [ { "date_opened": "09-05-2019", "closed_date": "25-10-2020", "currency": "NGN", "institution": "GUARANTY TRUST BANK PLC", "loan_status": "closed", "opening_balance": 2009930, "performance_status": "performing", "repayment_amount": 0, "repayment_frequency": "monthly", "repayment_schedule": [ { "date": "01-06-2019", "status": "performing" } ], "tenor": 12 } ] } ], "profile": { "full_name": "JOHN PAUL DOE", "date_of_birth": "15-01-1990", "gender": "male", "address_history": [ { "address": "12 SAMPLE STREET, IKEJA, LAGOS", "type": "residential", "date_reported": "30-11-2021" } ], "email_address": [ "john.doe@example.com" ], "phone_number": [ "08012345678" ], "identifications": [ { "no": "12345678901", "type": "BVN" }, { "no": "09876543212", "type": "NIN" } ] }, "providers": ["crc", "xds"] } } ``` #### `400` Bad Request Returned when the `provider` specified **is not valid**. In this case the response uses the format `application/problem+json`, since validation occurs **before** before processing the request: ```json { "status": 400, "title": "Bad Request", "detail": "Invalid request.", "type": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400", "errors": [ "provider must be one of: crc, xds, all" ] } ``` When the request contains incorrect data for the query, the error is returned with the service envelope (`serviceResultCode` reflects the HTTP code of the response): ```json { "serviceResultCode": 400, "serviceResultLog": "Sorry, lookup failed. Please check the details and try again", "serviceTime": "151", "serviceTransactionId": "08ac9699-dc9e-4cdc-81d7-264f71838309" } ``` #### `502` Bad Gateway Returned when the service is temporarily unavailable or its response could not be interpreted. The body uses the service envelope with `serviceResultCode: 500`: ```json { "serviceResultCode": 500, "serviceResultLog": "Service temporarily unavailable. Please try again later", "serviceTime": "3000", "serviceTransactionId": "38de2932-0f2h-7gff-14g0-597h04161632" } ``` #### `504` Gateway Timeout Timeout **error**, returned with the service envelope: ```json { "serviceResultCode": 504, "serviceResultLog": "Request timeout. Please try again", "serviceTime": "30000", "serviceTransactionId": "48ef3043-1g3i-8hgg-25h1-608i15272743" } ``` {% hint style="info" %} Authentication errors (`401`/`403`) are rejected by the **gateway before reaching the service** and **do** not use the envelope `serviceResultCode`. Platform validation errors use the format `application/problem+json`. See [Error handling](/docs.facephi-en/rest-api/identity-api/identity-api-reference/onboarding/kyc/nigeria.md#manejo-de-errores) for details of the three response forms. {% endhint %}