# Patascore

Financial health. Financial Prosperity. Financial wealth.

![](/files/-MXB4_QSsDi7FRexe3NR)

This document defines the new web service specifications for the Patascore services. It also illustrates the technologies and protocols used to support cross platform cross language interaction between the Patascore web services and Patascore clients. The API is REST based, and the data-exchange format is JSON. The API follows HTTP rules, enabling a wide range of HTTP clients can be used to interact with the API. 

## General Principals

### Root of the API

The API gateway offers a set of endpoints that can be reached via the following root URI’s depending on the environment: 

* Development/Testbed: \*\*<https://dev.api.patascore.com/**&#x20>;
* Production: \*\*<https://api.patascore.com/**&#x20>;

### Available HTTP VERBS

Patascore APIs use appropriate HTTP verbs for every action

| Method | Description                                                  |
| ------ | ------------------------------------------------------------ |
| GET    | Used for retrieving resources.                               |
| POST   | Used for creating resources and performing resource actions. |
| PUT    | Used for updating resources.                                 |
| DELETE | Used for deleting resources.                                 |

Data submitted to the API must be in **JSON** format, all responses from the API are also in **JSON** format. <br>

### Response Structure

The response structure for Patascore APIs follows the below format.

```javascript
{
   "status":200,
   "message":"Successfully logged in",
   "data":{
      "national_id":"12345678",
      "phone":"254707001122",
      "name":"Anthony Kamau Mathenge",
      "id":1328774,
      "uuid":"b493a591-46a3-46c7-8c1d-0537d00f977c"
   }
}
```

### Webhooks/Callback URLs

Webhooks are user-defined HTTP callbacks triggered by an event. Patascore uses webhooks to asynchronously let your application know when events happen Eg,

* Mpesa statement analytics process completion
* CRB data fetch completion

### Errors

Errors are always returned as an array of error objects, keyed by errors in the top level of a JSON object along with an error status & message

```javascript
{
   "status":400,
   "message":"Validation failed for one or more arguments",
   "errors":[
      "channel: Channel is mandatory"
   ]
}
```


# Authentication

Patascore authenticates incoming API requests using a client API key. This API key is required when making server-server requests. It should be passed in the header as a bearer token when making requests.This key should be kept confidential and stored only on the client server.&#x20;

The API key can be generated on the Patascore developer dashboard.<br>

{% tabs %}
{% tab title="Authentication Format" %}

```yaml
Authorization: Bearer {API KEY}
```

{% endtab %}
{% endtabs %}


# Customer Operations


# Register Customer

## Register Customer

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/customer/mfi/register`

This endpoint allows you to register a customer

#### Headers

| Name                                             | Type   | Description                                                    |
| ------------------------------------------------ | ------ | -------------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to track down who is emptying our stocks. |

#### Request Body

| Name                                           | Type   | Description                                            |
| ---------------------------------------------- | ------ | ------------------------------------------------------ |
| full\_name<mark style="color:red;">\*</mark>   | String | Full name                                              |
| national\_id<mark style="color:red;">\*</mark> | String | National ID Number                                     |
| phone<mark style="color:red;">\*</mark>        | String | Phone number                                           |
| location<mark style="color:red;">\*</mark>     | String | County of residence i.e Nairobi,Narok,Kirinyaga        |
| gender<mark style="color:red;">\*</mark>       | String | Gender of the user being registered i.e Male or Female |

{% tabs %}
{% tab title="200 Customer created successfully." %}

```javascript
{
   "status":200,
   "message":"Customer successfully registered",
   "data":{
      "id":132890,
      "full_name":"Anthony Kamau",
      "national_id":"21314151",
      "gender":"Female",
      "phone":"254707888888",
      "date_of_birth":"",
      "date_registered": "13/03/2023 11:18",
      "name":"Anthony Kamau",
      "location":132890,
      "uuid":"c211984f-b5a5-45fb-ae38-9f22fe0465d9",
      "email":""
   }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload" %}

```javascript
{ 
 "full_name": "Anthony Kamau", 
 "national_id": "21314151", 
 "phone": "0707888888",
 "gender": "Female" 
 "location": "Kwale" 
}
```

{% endtab %}
{% endtabs %}


# Fetch Customer

## Fetch Customer

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/customer/mfi/info/fetch?id=:id`

This endpoint allows you to get free cakes.

#### Headers

| Name                                             | Type   | Description                                                           |
| ------------------------------------------------ | ------ | --------------------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to track down who is emptying our stocks.        |
| id<mark style="color:red;">\*</mark>             | Number | The API will do its best to find a cake matching the provided recipe. |

{% tabs %}
{% tab title="200 Customer successfully retrieved." %}

```javascript
{
   "status":200,
   "message":"Customer info successfully fetched",
   "data":{
      "id":132890,
      "full_name":"Anthony Kamau",
      "national_id":"21314151",
      "gender":"Female",
      "phone":"254707888888",
      "date_of_birth":"",
      "date_registered": "13/03/2023 11:18",
      "name":"Anthony Kamau",
      "location":132890,
      "uuid":"c211984f-b5a5-45fb-ae38-9f22fe0465d9",
      "email":""
   }
}
```

{% endtab %}
{% endtabs %}


# Verification & Credit Data Operations

The table below includes the Identifier Type arguments accepted for the Fetch verification data API endpoints

| Identifier Type | Description        |
| --------------- | ------------------ |
| national\_id    | National ID Number |


# Fetch Verification

## Fetch Verification (Sync)

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/sync/verification`

This endpoint allows you to verify a customer details synchronously.

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

#### Request Body

<table><thead><tr><th>Name</th><th width="163">Type</th><th>Description</th></tr></thead><tbody><tr><td>identifier_type<mark style="color:red;">*</mark></td><td>String</td><td>The identifier type being used for the verification (national_id or passport_no)</td></tr><tr><td>identifier<mark style="color:red;">*</mark></td><td>String</td><td>Identifier value</td></tr><tr><td>first_name<mark style="color:red;">*</mark></td><td>String</td><td>First name of the individual</td></tr><tr><td>last_name<mark style="color:red;">*</mark></td><td>String</td><td>Last name of the individual</td></tr></tbody></table>

{% tabs %}
{% tab title="200: OK Verification successfully retrieved. (NATIONAL ID)" %}

```json
{
    "status": 200,
    "message": "Verification data fetched successfully",
    "data": {
        "national_id": "99999999",
        "full_name": "Marangi Peter Mbiu",
        "surname": "Marangi",
        "other_names": "Peter Mbiu",
        "first_name": "Peter",
        "gender": "M",
        "date_of_birth": "9/25/1989 12:00:00 AM",
        "place_of_birth": "ELDORET EAST\nDISTRICT - ELDORET EAST",
        "citizenship": "Kenyan",
        "occupation": "UNEMPLOYED",
        "place_of_live": "ELDORET EAST DISTRICT - ELDORET EAST",
        "date_of_issue": "9/25/2014 12:00:00 AM",
        "photo": "",
        "clan": "",
        "ethnic_group": "",
        "family": "",
        "reg_office": "",
        "serial_number": "124316781"
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload - National ID" %}

```json
{ 
 "identifier_type": "national_id", 
 "identifier": "99999999",
 "first_name": "Peter Murungi",
 "last_name": "Doe",
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload - Passport" %}

```json
{ 
 "identifier_type": "passport_no", 
 "identifier": "AK078R474",
 "first_name": "Jane",
 "last_name": "Doe",
}
```

{% endtab %}
{% endtabs %}

**Response Codes**

| Code                      | Meaning                                        |
| ------------------------- | ---------------------------------------------- |
| 200 OK                    | Successfully verified the identity.            |
| 400 Bad Request           | Invalid request parameters.                    |
| 401 Unauthorized          | Invalid or missing authentication credentials. |
| 404 Not Found             | No data found for the requested identifier.    |
| 500 Internal Server Error | An error occurred on the server side.          |
| 503 Service Unavailable   | IPRS systems are down.                         |

### **Error Handling** <a href="#error-handling" id="error-handling"></a>

Errors are returned in the following format:

```json
{ 
    "status": "error code",   
    "message": "error message" 
}
```

#### **Common HTTP Status Codes** <a href="#common-http-status-codes" id="common-http-status-codes"></a>

| Code                      | Message                                                 |
| ------------------------- | ------------------------------------------------------- |
| 400 Bad Request           | The request was invalid or missing required parameters. |
| 401 Unauthorized          | Authentication failed or the token is missing.          |
| 403 Forbidden             | Access to the resource is denied.                       |
| 404 Not Found             | The requested resource could not be found.              |
| 500 Internal Server Error | An error occurred on the server side.                   |
| 503 Service Unavailable   | IPRS systems are down.                                  |

#### **Error Responses** <a href="#error-responses" id="error-responses"></a>

**Bad Request (400)**

```json
{   
    "status": 400,   
    "message": "identifier_type is required" 
}
```

```json
{
  "status": 400,
  "message": "Identifier should contain only digits for national_id"
}
```

```json
{
  "status": 400,
  "message": "Identifier should be between 6 and 10 digits long for national_id"
}
```

**Internal Server Error (500)**

```json
{    
    "status": 500,    
    "message": "Internal server error: Contact support@pezesha.freshdesk.com" 
}
```

**Service Unavailable (503)**

```json
{
    "status": 503,    
    "message": "IPRS systems are experiencing a nationwide downtime." 
}
```

&#x20;**Rate Limiting**

To ensure fair usage, API requests are subject to rate limits. Exceeding these limits will result in a **429 Too Many Requests** response. The current setting prevents duplicate requests within a **2-minute window**.

```json
{
   "status": 429,
   "message": "Too many requests: Please wait before retrying."
}
```


# Fetch Verification (Async)

## Fetch Verification (Async)

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/verification`

This endpoint allows you to verify a customer details asynchronously.

#### Headers

| Name                                             | Type   | Description                                     |
| ------------------------------------------------ | ------ | ----------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to identifer the api user. |

#### Request Body

| Name                                               | Type   | Description                                                        |
| -------------------------------------------------- | ------ | ------------------------------------------------------------------ |
| identifier\_type<mark style="color:red;">\*</mark> | String | The identifier type being used for the verification (national\_id) |
| identifier<mark style="color:red;">\*</mark>       | String | The identifier value                                               |
| callback\_url<mark style="color:red;">\*</mark>    | String | Callback url to send verification response to                      |

{% tabs %}
{% tab title="200 Request successfully received." %}

```javascript
{
   "status":202,
   "message":"Verification data fetch Process initiated",
   "data":{
      "reference_id":"b19234cc-2adf-4c1c-a6f8-91684254466c"
   }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload" %}

```javascript
{
   "identifier_type":"national_id",
   "identifier":"21626048",
   "first_name": "Jane",
   "last_name": "Doe",
   "callback_url":"https://webhook.site/0f81808a-0134"
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Callback Payload" %}

```javascript
{
   "status":200,
   "message":"Verification data successfully fetched",
   "reference_id":"b19234cc-2adf-4c1c-a6f8-91684254466c",
   "data":{
      "national_id":"21626048",
      "full_name":"CURL JANE DOE",
      "gender":"M",
      "surname":"CURL",
      "date_of_birth":"01-02-1984",
      "other_names":"JANE DOE"
   }
}
```

{% endtab %}
{% endtabs %}


# Mobiloanscore (Sync)

## Get Mobiloanscore (Sync)

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/sync/mobiloanscore`

This endpoint allows you to get free cakes.

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| Authentication | string | Authentication token |

#### Request Body

| Name         | Type   | Description       |
| ------------ | ------ | ----------------- |
| first\_name  | string | Users first name  |
| last\_name   | string | Users last name   |
| national\_id | string | Users national is |

{% tabs %}
{% tab title="200 Mobiloanscore successfully retrieved." %}

```javascript
{
    "status": 200,
    "message": "Mobiloan score data successfully fetched",
    "data": {
        "summary": {
            "pa_open_mobi_loan_accounts": 0,
            "npa_closed_accounts": 0,
            "npa_open_accounts": 1,
            "pa_closed_accounts": 0,
            "pa_accounts_with_dh": 0,
            "last_mobi_loan_listing_date_my_sector": "",
            "pa_accounts": 0,
            "pa_closed_mobi_loan_accounts": 0,
            "mobi_loan_accounts": 1,
            "enquiries31_to60_days": 0,
            "bounced_cheques": 0,
            "min_mobi_loan_principal_amount": 4000.0,
            "avg_mobi_loan_principal_amount": 4000.0,
            "last_mobi_loan_listing_date_other_sectors": null,
            "legal_suits": 0,
            "npa_closed_mobi_loan_accounts": 0,
            "mobi_loans_score": "-1",
            "pa_open_mobi_loan_accounts_with_dh": 0,
            "fraudulent_cases": 0,
            "pa_open_accounts_with_dh": 0,
            "pa_closed_mobi_loan_accounts_with_dh": 0,
            "npa_open_mobi_loan_accounts": 1,
            "last_mobi_loan_principal_amount": 4000.0,
            "credit_history": 50,
            "enquiries_last30_days": 0,
            "max_mobi_loan_principal_amount": 4000.0,
            "credit_applications": 0,
            "pa_open_accounts": 0,
            "enquiries61_to90_days": 0,
            "npa_accounts": 1,
            "enquiries91_days": 0,
            "pa_closed_accounts_with_dh": 0
        },
        "phone_numbers": [
            {
                "phone_number": "254729760175",
                "phone_type": "MOBILE"
            }
        ],
        "product": "PRODUCT131",
        "personal_profile": {
            "national_id": "99001122",
            "occupation": null,
            "gender": "",
            "date_of_birth": "12/31/1969 00:00:00 AM",
            "citizenship": null,
            "photo": null,
            "other_names": "John",
            "serial_number": null,
            "middle_name": null,
            "message": null,
            "place_of_live": null,
            "place_of_birth": null,
            "full_name": "Doe John",
            "reg_office": null,
            "date_of_issue": null,
            "surname": "Doe",
            "clan": null,
            "ethnic_group": null,
            "family": null,
            "first_name": null,
            "status": null
        },
        "score_output": {
            "reason_code_aarc1": "-",
            "reason_code_aarc2": "-",
            "reason_code_aarc3": "-",
            "reason_code_aarc4": "-",
            "probability": "",
            "grade": "YY",
            "positive_score": null,
            "mobi_loans_score": "-1"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload" %}

```javascript
{
    "first_name": "John",
    "last_name": "Doe",
    "national_id": "99999999"
}
```

{% endtab %}
{% endtabs %}


# Mobiloanscore (Async)

## Get Mobiloanscore (Async)

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/mobiloanscore`

This endpoint allows you to get a customer's mobiloanscore asynchronously.

#### Headers

| Name                                             | Type   | Description          |
| ------------------------------------------------ | ------ | -------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token |

#### Request Body

| Name                                            | Type   | Description                               |
| ----------------------------------------------- | ------ | ----------------------------------------- |
| first\_name<mark style="color:red;">\*</mark>   | String | users first name                          |
| last\_name<mark style="color:red;">\*</mark>    | String | users last name                           |
| national\_id<mark style="color:red;">\*</mark>  | String | users national id                         |
| callback\_url<mark style="color:red;">\*</mark> | String | Callback url to send mobiloan response to |

{% tabs %}
{% tab title="200 Request successfully received." %}

```javascript
{
   "status":202,
   "message":"Mobiloan score fetch Process initiated",
   "data":{
      "reference_id":"c6966641-e519-44b6-9e98-eb2b3be0db76"
   }
}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="JSON Payload" %}

```javascript
{
    "first_name": "John",
    "last_name": "Doe",
    "national_id": "99999999"
    "callback_url":"https://webhook.site/0f81808a"
}
```

{% endtab %}
{% endtabs %}

```javascript
{
    "status": 200,
    "message": "Mobiloan score data successfully fetched",
   "reference_id":"c6966641-e519-44b6-9e98-eb2b3be0db76",
    "data": {
        "summary": {
            "pa_open_mobi_loan_accounts": 0,
            "npa_closed_accounts": 0,
            "npa_open_accounts": 1,
            "pa_closed_accounts": 0,
            "pa_accounts_with_dh": 0,
            "last_mobi_loan_listing_date_my_sector": "",
            "pa_accounts": 0,
            "pa_closed_mobi_loan_accounts": 0,
            "mobi_loan_accounts": 1,
            "enquiries31_to60_days": 0,
            "bounced_cheques": 0,
            "min_mobi_loan_principal_amount": 4000.0,
            "avg_mobi_loan_principal_amount": 4000.0,
            "last_mobi_loan_listing_date_other_sectors": null,
            "legal_suits": 0,
            "npa_closed_mobi_loan_accounts": 0,
            "mobi_loans_score": "-1",
            "pa_open_mobi_loan_accounts_with_dh": 0,
            "fraudulent_cases": 0,
            "pa_open_accounts_with_dh": 0,
            "pa_closed_mobi_loan_accounts_with_dh": 0,
            "npa_open_mobi_loan_accounts": 1,
            "last_mobi_loan_principal_amount": 4000.0,
            "credit_history": 50,
            "enquiries_last30_days": 0,
            "max_mobi_loan_principal_amount": 4000.0,
            "credit_applications": 0,
            "pa_open_accounts": 0,
            "enquiries61_to90_days": 0,
            "npa_accounts": 1,
            "enquiries91_days": 0,
            "pa_closed_accounts_with_dh": 0
        },
        "phone_numbers": [
            {
                "phone_number": "254729760175",
                "phone_type": "MOBILE"
            }
        ],
        "product": "PRODUCT131",
        "personal_profile": {
            "national_id": "99001122",
            "occupation": null,
            "gender": "",
            "date_of_birth": "12/31/1969 00:00:00 AM",
            "citizenship": null,
            "photo": null,
            "other_names": "John",
            "serial_number": null,
            "middle_name": null,
            "message": null,
            "place_of_live": null,
            "place_of_birth": null,
            "full_name": "Doe John",
            "reg_office": null,
            "date_of_issue": null,
            "surname": "Doe",
            "clan": null,
            "ethnic_group": null,
            "family": null,
            "first_name": null,
            "status": null
        },
        "score_output": {
            "reason_code_aarc1": "-",
            "reason_code_aarc2": "-",
            "reason_code_aarc3": "-",
            "reason_code_aarc4": "-",
            "probability": "",
            "grade": "YY",
            "positive_score": null,
            "mobi_loans_score": "-1"
        }
    }
}
```


# Business Verification


# Business Verification

This endpoint allows you to verify a business.

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/business/verification`

#### Headers

| Name                                             | Type   | Description                                               |
| ------------------------------------------------ | ------ | --------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to track who is making the requests. |

#### Request Body

| Name                                               | Type   | Description                            |
| -------------------------------------------------- | ------ | -------------------------------------- |
| registration\_no<mark style="color:red;">\*</mark> | String | Business registration number to verify |

#### Request Example

```json
{
    "registration_no": "PVT-GYUPEKK"
}
```

#### 200: Response Example

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "status": 200,
    "message": "Business verification data fetched successfully",
    "data": {
        "id": 26,
        "verified": "true",
        "status": "registered",
        "registrationDate": "9 April 1998",
        "registrationNo": "PVT-FYUVQBQR",
        "businessName": "Sodapop Inc",
        "branch": null,
        "partners": "[
            {"type":"director_shareholder","name":"JANE DOE","idType":"citizen","idNumber":"67983412","shares":[{"shareCount":"100","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"JOHN DOE","idType":"citizen","idNumber":"78653421","shares":[{"shareCount":"850","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"kenya impact incubator limited","idType":"local_company","idNumber":"CPR/2015/652153","shares":[{"shareCount":"50","nominalValue":null,"name":"ORDINARY"}]}]",
        "email": "hello@sodapop.com",
        "phoneNumber": "+254712345678",
        "postalAddress": "P O BOX 68999 - 00622",
        "physicalAddress": "Sodapop Plaza/Land Reference Number: 1/13413/Kamburu Drive , Kindaruma Road, Fl: 5, Room/Door:  502, LR NO 312/17830 HSE NO 6 THOGOTO ROAD NAIROBI",
        "shareCapital": "[{"shareCount":1000,"nominalValue":1000.0,"name":"ORDINARY"}]",
        "encumbrances": "[]"
    }
}
```

{% endtab %}
{% endtabs %}

#### 202: Response Example

In this case, please use the [Fetch Results](https://docs.patascore.com/business-verification/fetch-results-optional) endpoint to retrieve results.

{% tabs %}
{% tab title="202: PENDING" %}

```json
{
    "status": 202,
    "message": "Search in progress. Please try again later",
    "data": {
        "batch_id": "afd91316-4132-4814-b494-b9361c8513r7"
    }
}
```

{% endtab %}
{% endtabs %}

#### Response Codes

| Code                      | Meaning                                        |
| ------------------------- | ---------------------------------------------- |
| 200 OK                    | Successfully verified the identity.            |
| 400 Bad Request           | Invalid request parameters.                    |
| 401 Unauthorized          | Invalid or missing authentication credentials. |
| 403 Forbidden             | Unauthorized                                   |
| 404 Not Found             | No data found for the requested identifier.    |
| 500 Internal Server Error | An error occurred on the server side.          |
| 503 Service Unavailable   | BRS systems are down.                          |
| 202 Process is pending    | Could not get result now. Try again later.     |
| 429 Rate Limit Exceeded   | Rate Limit exceeded                            |
| 409 Conflict              | Request ongoing                                |

### **Error Handling** <a href="#error-handling" id="error-handling"></a>

Errors are returned in the following format:

```json
{ 
    "status": "error code",   
    "message": "error message" 
}
```

#### **Common HTTP Status Codes** <a href="#common-http-status-codes" id="common-http-status-codes"></a>

| Code                      | Message                                                 |
| ------------------------- | ------------------------------------------------------- |
| 400 Bad Request           | The request was invalid or missing required parameters. |
| 401 Unauthorized          | Authentication failed or the token is missing.          |
| 403 Forbidden             | Access to the resource is denied.                       |
| 404 Not Found             | The requested resource could not be found.              |
| 500 Internal Server Error | An error occurred on the server side.                   |
| 503 Service Unavailable   | BRS systems are down.                                   |
| 429 Rate Limit Exceeded   | Rate Limit exceeded                                     |
| 409 Conflict              | Request ongoing                                         |

#### **Error Responses** <a href="#error-responses" id="error-responses"></a>

**Bad Request (400)**

```json
{   
    "status": 400,   
    "message": "Bad request" 
}
```

**Unauthenticated (401)**

```json
{   
    "status": 401,   
    "message": "Unauthenticated" 
}
```

**Unauthorized (403)**

```json
{   
    "status": 403,   
    "message": "Insufficient wallet balance" 
}
```

**Not Found (404)**

```json
{   
    "status": 404,   
    "message": "No data found for this business identifier" 
}
```

**Internal Server Error (500)**

```json
{    
    "status": 500,    
    "message": "Internal server error: Contact support@pezesha.freshdesk.com" 
}
```

**Service Unavailable (503)**

```json
{
    "status": 503,    
    "message": "BRS systems are experiencing a downtime." 
}
```

#### Conflict

```json
{
    "status": 409,    
    "message": "Request ongoing for this registration number." 
}
```

&#x20;**Rate Limiting**

To ensure fair usage, API requests are subject to rate limits. Exceeding these limits will result in a **429 Too Many Requests** response. The current setting prevents duplicate requests within a **2-minute window**.

```json
{
   "status": 429,
   "message": "Too many requests: Please wait before retrying."
}
```


# Fetch Results (Optional)

This endpoint allows you to retrieve business verification data for pending searches cases: Cases where the verification endpoint returned 202.

<mark style="color:green;">`POST`</mark>` ``{{BASE_URL}}/api/v1/business/results?batch_id=batchId`

### Request Params

<table><thead><tr><th width="195">Name</th><th width="184">Type</th><th>Description</th></tr></thead><tbody><tr><td>batch_id<mark style="color:red;">*</mark></td><td>String</td><td>batch id returned in the verification endpoint </td></tr></tbody></table>

#### Response Example

{% tabs %}
{% tab title="200: OK" %}

```json
{
    "status": 200,
    "message": "Business verification data fetched successfully",
    "data": {
        "id": 26,
        "verified": "true",
        "status": "registered",
        "registrationDate": "9 April 1998",
        "registrationNo": "PVT-FYUVQBQR",
        "businessName": "Sodapop Inc",
        "branch": null,
        "partners": "[
            {"type":"director_shareholder","name":"JANE DOE","idType":"citizen","idNumber":"67983412","shares":[{"shareCount":"100","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"JOHN DOE","idType":"citizen","idNumber":"78653421","shares":[{"shareCount":"850","nominalValue":null,"name":"ORDINARY"}]},
            {"type":"director_shareholder","name":"kenya impact incubator limited","idType":"local_company","idNumber":"CPR/2015/652153","shares":[{"shareCount":"50","nominalValue":null,"name":"ORDINARY"}]}]",
        "email": "hello@sodapop.com",
        "phoneNumber": "+254712345678",
        "postalAddress": "P O BOX 68999 - 00622",
        "physicalAddress": "Sodapop Plaza/Land Reference Number: 1/13413/Kamburu Drive , Kindaruma Road, Fl: 5, Room/Door:  502, LR NO 312/17830 HSE NO 6 THOGOTO ROAD NAIROBI",
        "shareCapital": "[{"shareCount":1000,"nominalValue":1000.0,"name":"ORDINARY"}]",
        "encumbrances": "[]"
    }
}
```

{% endtab %}

{% tab title="202: PENDING" %}

```json
{
    "status": 202,
    "message": "Search in progress. Please try again later",
    "data": {
        "batch_id": "afd91316-4132-4814-b494-b9361c8513r7"
    }
}
```

{% endtab %}
{% endtabs %}

#### Response Codes

| Code                      | Meaning                                        |
| ------------------------- | ---------------------------------------------- |
| 200 OK                    | Successfully verified the identity.            |
| 400 Bad Request           | Invalid request parameters.                    |
| 401 Unauthorized          | Invalid or missing authentication credentials. |
| 403 Forbidden             | Unauthorized                                   |
| 404 Not Found             | No data found for the requested identifier.    |
| 500 Internal Server Error | An error occurred on the server side.          |
| 503 Service Unavailable   | BRS systems are down.                          |
| 202 Process is pending    | Could not get result now. Try again later.     |
| 429 Rate Limit Exceeded   | Rate Limit exceeded                            |

### **Error Handling** <a href="#error-handling" id="error-handling"></a>

Errors are returned in the following format:

```json
{ 
    "status": "error code",   
    "message": "error message" 
}
```

#### **Common HTTP Status Codes** <a href="#common-http-status-codes" id="common-http-status-codes"></a>

| Code                      | Message                                                 |
| ------------------------- | ------------------------------------------------------- |
| 400 Bad Request           | The request was invalid or missing required parameters. |
| 401 Unauthorized          | Authentication failed or the token is missing.          |
| 403 Forbidden             | Access to the resource is denied.                       |
| 404 Not Found             | The requested resource could not be found.              |
| 500 Internal Server Error | An error occurred on the server side.                   |
| 503 Service Unavailable   | BRS systems are down.                                   |
| 429 Rate Limit Exceeded   | Rate Limit exceeded                                     |

#### **Error Responses** <a href="#error-responses" id="error-responses"></a>

**Bad Request (400)**

```json
{   
    "status": 400,   
    "message": "Bad request" 
}
```

**Unauthenticated (401)**

```json
{   
    "status": 401,   
    "message": "Unauthenticated" 
}
```

**Unauthorized (403)**

```json
{   
    "status": 403,   
    "message": "Insufficient wallet balance" 
}
```

**Not Found (404)**

```json
{   
    "status": 404,   
    "message": "No data found for this business identifier" 
}
```

**Internal Server Error (500)**

```json
{    
    "status": 500,    
    "message": "Internal server error: Contact support@pezesha.freshdesk.com" 
}
```

**Service Unavailable (503)**

```json
{
    "status": 503,    
    "message": "BRS systems are experiencing a downtime." 
}
```

#### Conflict

```json
{
    "status": 409,    
    "message": "Request ongoing for this registration number." 
}
```

&#x20;**Rate Limiting**

To ensure fair usage, API requests are subject to rate limits. Exceeding these limits will result in a **429 Too Many Requests** response. The current setting prevents duplicate requests within a **2-minute window**.

```json
{
   "status": 429,
   "message": "Too many requests: Please wait before retrying."
}
```


# MPESA Operations


# Check for User Statement

## Check for user statement

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/statement/check?national_id=:national_id`

This endpoint allows you to check whether a user has any past extracted and analysed statements

#### Query Parameters

| Name                                           | Type   | Description          |
| ---------------------------------------------- | ------ | -------------------- |
| national\_id<mark style="color:red;">\*</mark> | String | National id to check |

#### Headers

| Name                                             | Type   | Description          |
| ------------------------------------------------ | ------ | -------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token |

{% tabs %}
{% tab title="200 Statement check successfully retrieved." %}

```javascript
{
   "status":200,
   "message":"Statement check successful",
   "data":{
      "exists":false
   }
}
```

{% endtab %}
{% endtabs %}


# Upload Statement (Extraction)

Upload consumer, till and paybill mpesa statement for analysis and credit scoring

## Upload Mpesa Statments

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/statements/mpesa/upload`

This endpoint allows you to upload Mpesa Statements for extraction, analysis and scoring

#### Headers

| Name                                             | Type   | Description                                   |
| ------------------------------------------------ | ------ | --------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token to track down API usage. |

#### Request Body

| Name                                              | Type   | Description                                                                                     |
| ------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------- |
| national\_id<mark style="color:red;">\*</mark>    | String | Customer's national ID                                                                          |
| file<mark style="color:red;">\*</mark>            | String | Base64 encoded file string                                                                      |
| file\_name<mark style="color:red;">\*</mark>      | String | Unchanged Mpesa Statement Name                                                                  |
| callback\_url<mark style="color:red;">\*</mark>   | String | Where to send result                                                                            |
| statement\_type<mark style="color:red;">\*</mark> | String | Statement being uploaded only one of three user\_statement, paybill\_statement, till\_statement |
| passcode<mark style="color:red;">\*</mark>        | String | The file's passcode                                                                             |

{% tabs %}
{% tab title="200 Statement saved successfully" %}

```json
{
   "status": 202,
   "message": "Statement saved successfully. Extraction process initiated",
   "data":{
      "reference_id": "22050643-73b9-4eec-ac73-4572d643ac1c",
      "name": "JOHN DOE",
      "phone_number": "254700123456",
      "statement_type": "user_statement",
       "short_code": null,
       "statement_period": "17 Oct 2022 - 17 Jan 2023"
   }
}
```

{% endtab %}
{% endtabs %}

### Statement upload request Example

```json
{
  "national_id": "546444747",
  "file_name": "MPESA_Statement_2022-12-07_to_2023-03-07_254707888888_54646.pdf",
  "callback_url": "https://webhook.site/45349498-57fc-4ab1-bcdb-0b0b1a657932",
  "statement_type": "user_statement",
  "file":"base 64 file string",
  "passcode": "12345"
}
```

### Callback Response

```json
{
   "data": {
       {
           "national_id": 1001,
           "phone_number": "M12345",
           “other_details”: { ... },
           
            "statement_details": [
                    {
                        "transaction_id": "PLV6XV3WK2",
                        "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                        "received_amount": 575.65,
                        "sent_amount": 0,
                        "balance_then": 236363.31,
                        "transaction_datetime": "2024-09-28T00:00:00"
                    },
                    {
                    "transaction_id": "PLV6XV3WK3",
                    "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                    "received_amount": 575.65,
                    "sent_amount": 0,
                    "balance_then": 1000.31,
                    "transaction_datetime": "2024-09-28T00:00:00"
                }
            ],
            
              "total_fuliza_betting_6m": 0,
              "total_fuliza_loan_repayment_6m": 0,
              "total_fuliza_airtime_6m": 0,
              "total_fuliza_bill_payment_6m": 0,
              "total_fuliza_merchant_payment_6m": 0,
              "total_fuliza_p2p_transfer_6m": 0,
              "total_fuliza_agent_withdrawal_6m": 0,
              "total_fuliza_debit_count_6m": 0,
              "total_fuliza_debit_sum_6m": 0,
              "total_mobile_loan_received_6m": 0,
              "total_mobile_loan_repaid_6m": 0,
              "total_mshwari_loan_repayment_6m": 0,
              "total_mshwari_loan_deposit_6m": 0,
              "total_mshwari_withdrawal_6m": 0,
              "total_mshwari_savings_deposit_6m": 0,
              "total_p2p_received_6m": 18100,
              "total_p2p_sent_6m": 696447,
              "mobile_loan_count_6m": 0,
            
           "score_data": {
               "reason_code_1": "Low number of transactions",
               "reason_code_2": "Low frequency of transactions",
               "reason_code_3": "Customer inactive for a long period",
               "reason_code_4": "Low transaction volumes",
               "probability": "45.56",
               "grade": "GG",
               "credit_score": "412",
               "limit": "[4386.0, 6579.0]"
           },           
          "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           },
           "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           }

        },
        
        "fraud_data": {
          "message": "successfully obtained IPRS data",
          "national_id": "550000055",
          "statement_name": [
            "JOHN",
            "ALPHA",
            "DOE"
          ],
          "customer_name": [
            "Peter",
            "Marangi"
          ],
          "similarity_score": 0,
          "verified_status": "no match"
        },
    }
}
```


# Extraction Status

## Extraction Status

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/statement/mpesa/status?reference_id=:reference_id`

This endpoint allows you to get the extraction status of an uploaded statement

#### Query Parameters

| Name                                            | Type   | Description            |
| ----------------------------------------------- | ------ | ---------------------- |
| reference\_id<mark style="color:red;">\*</mark> | String | statement reference id |

#### Headers

| Name                                             | Type   | Description                 |
| ------------------------------------------------ | ------ | --------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication bearer token |

{% tabs %}
{% tab title="200 Status successfully retrieved." %}

```json
{
   "status":200,
   "message":"Extraction process status successfully fetched",
   "data":{
      "message":"Statement scoring in progresss",
      "status":1
   }
}
```

{% endtab %}
{% endtabs %}


# Scoring Results

Get the credit scoring results of an uploaded Mpesa statement statement

## Get Statement Scores

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/statements/mpesa/report?ref_id=:reference_id`

This endpoint allows you to get the credit scoring results of an mpesa statement

#### Query Parameters

| Name                                      | Type   | Description                               |
| ----------------------------------------- | ------ | ----------------------------------------- |
| ref\_id<mark style="color:red;">\*</mark> | String | reference id in statement upload response |

#### Headers

| Name                                             | Type   | Description                                               |
| ------------------------------------------------ | ------ | --------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to track who is making the requests. |

{% tabs %}
{% tab title="200 Categories successfully retrieved." %}

```json
{
    "status": 200,
    "message": "Mpesa statement score report fetched successfully",
    {
   "data": {
       {
           "national_id": 1001,
           "phone_number": "M12345",
           “other_details”: { ... },
           
            "statement_details": [
                    {
                        "transaction_id": "PLV6XV3WK2",
                        "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                        "received_amount": 575.65,
                        "sent_amount": 0,
                        "balance_then": 236363.31,
                        "transaction_datetime": "2024-09-28T00:00:00"
                    },
                    
                    {
                    "transaction_id": "PLV6XV3WK3",
                    "transaction_type": "Customer Transfer to 0721***691 - LEON NYONGA ARIGI",
                    "received_amount": 575.65,
                    "sent_amount": 0,
                    "balance_then": 1000.31,
                    "transaction_datetime": "2024-09-28T00:00:00"
                }
            ],
            
           "score_data": {
               "reason_code_1": "Low number of transactions",
               "reason_code_2": "Low frequency of transactions",
               "reason_code_3": "Customer inactive for a long period",
               "reason_code_4": "Low transaction volumes",
               "probability": "45.56",
               "grade": "GG",
               "credit_score": "412",
               "limit": "[4386.0, 6579.0]"
           },
           
          "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           },
           
           "received_amount_trend": {
               "2023-11-30": 603407.4,
               "2023-12-31": 858879.0
           },
           
           "sent_amount_trend": {
               "2023-11-30": 214903.6,
               "2023-12-31": 357154.7
           },
           
           "balance_amount_trend": {
               "2023-11-30": 25844.450764,
               "2023-12-31": 35800.46298
           }

        },
        "fraud_data": {
          "message": "successfully obtained IPRS data",
          "national_id": "550000055",
          "statement_name": [
            "JOHN",
            "ALPHA",
            "DOE"
          ],
          "customer_name": [
            "Peter",
            "Marangi"
          ],
          "similarity_score": 0,
          "verified_status": "no match"
        },
    }
  }
}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```json
{
    "status": 400,
    "message": "Statment Not Found"
}
```

{% endtab %}
{% endtabs %}


# Bank Operations


# Upload Statement (Extraction)

Upload Bank statement for analysis and credit scoring

## Upload Bank Statements

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/bank/statements`

This endpoint allows you to upload Bank Statements for extraction, analysis and scoring

#### Headers

| Name                                             | Type   | Description                                   |
| ------------------------------------------------ | ------ | --------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | string | Authentication token to track down API usage. |

#### Request Body

| Name                                            | Type   | Description                                                  |
| ----------------------------------------------- | ------ | ------------------------------------------------------------ |
| national\_id<mark style="color:red;">\*</mark>  | String | User's national ID                                           |
| file<mark style="color:red;">\*</mark>          | String | Base64 encoded file string                                   |
| file\_name<mark style="color:red;">\*</mark>    | String | Name of the file                                             |
| callback\_url<mark style="color:red;">\*</mark> | String | Where to send result                                         |
| bank<mark style="color:red;">\*</mark>          | String | Statement bank (Lowercase: im, equity, sbm, kcb, absa, e.tc) |
| passcode                                        | String | Passcode for encrypted files                                 |

{% tabs %}
{% tab title="200 Statement saved successfully" %}

```javascript
{
    "status": 202,
    "message": "Statement saved successfully. Extraction process initiated",
    "data": {
        "reference_id": "bdcb2d95-ad53-4245-8af7-f745ae7d4f33",
    }
}
```

{% endtab %}

{% tab title="400 In case of error" %}

```javascript
{
    "status": 400,
    "message": "Validation failed for one or more arguments",
    "errors": [
        "nationalId: must not be null",
        "file: Base64 encoded file is required",
        "file: must not be null",
        "nationalId: National Id is required"
    ]
}
```

{% endtab %}
{% endtabs %}

### Statement upload request Example

```javascript
{
    "national_id": "27365875",
    "callback_url": "https://webhook.site/1b8a88f9-ba46-4bfc-a739-15ca2f5d964b",
    "file": "base 64 file string",
    "bank": "absa",
    "file_name": "27365875.pdf"
}
```

### Statement Callback Response Example

```javascript
{
    "ref_id": "9873fed7-742c-4f8b-8d57-9e2ab9c0f50d",
    "status": "success",
    "message": "Bank Statement analytics callback successfully fetched",
    "data": {
        "ref_id": "a6dc2fb0-c918-418c-8007-dcdf74a9a9ed",
        "national_id": "27365875",
        "score_data": {
            "initial_score": 327.0,
            "bank_score": 327.0,
            "bank_version": "v1",
            "limit": [
                273394.0,
                410091.0
            ]
        },
        "report": {
            "overall": {
                "national_id": "27365875",
                "transaction_id": "bdb0dbe4051521dfd496f6d53503a4680b1b6de09e979c3f42f6bce7b4de32dd",
                "transaction_datetime": "2022-07-01T00:00:00",
                "transaction_details": 0,
                "sent_amount": 1000.0,
                "received_amount": 0.0,
                "balance_then": 21000.6,
                "bank_name": "absa",
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "statement_days": 29,
                "statement_months": 0.97,
                ...
                "received_amount_trend": {
                    "2022-07-31": 776950.85
                },
                "sent_amount_trend": {
                    "2022-07-31": 716483.35
                },
                "balance_amount_trend": {
                    "2022-07-31": 57584.3687772926
                },
                "business_label": 0,
                "initial_score": 327.0,
                "bank_score": 327.0,
                "score": 327.0,
                "bank_version": "v1",
                "limit": "[273394.0, 410091.0]"
            },
            "1y": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "6m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "3m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "1m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            }
        },
        "fraud_data": null,
        "created_at": "2025-06-20T12:00:58"
    }
}
```


# Scoring Results

Get the credit scoring results of an uploaded Mpesa statement statement

## Get Statement Scores

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/bank/statements?ref_id=:ref_id`

This endpoint allows you to get the credit scoring results of an mpesa statement

#### Query Parameters

| Name                                      | Type   | Description                            |
| ----------------------------------------- | ------ | -------------------------------------- |
| ref\_id<mark style="color:red;">\*</mark> | String | reference in statement upload response |

#### Headers

| Name                                             | Type   | Description                                               |
| ------------------------------------------------ | ------ | --------------------------------------------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token to track who is making the requests. |

{% tabs %}
{% tab title="200 Score successfully retrieved." %}

```javascript
{
    "status": 200,
    "message": "Statement Analytics successfully fetched",
    "data": {
        "ref_id": "a6dc2fb0-c918-418c-8007-dcdf74a9a9ed",
        "national_id": "27365875",
        "fraud_data": null,
        "score_data": {
            "initial_score": 327.0,
            "bank_score": 327.0,
            "bank_version": "v1",
            "limit": [
                273394.0,
                410091.0
            ]
        },
        "report": {
            "overall": {
                "national_id": "27365875",
                "transaction_id": "bdb0dbe4051521dfd496f6d53503a4680b1b6de09e979c3f42f6bce7b4de32dd",               
                "transaction_details": 0,
                "sent_amount": 1000.0,
                "received_amount": 0.0,
                "balance_then": 21000.6,
                "bank_name": "absa",
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "statement_days": 29,
                "statement_months": 0.97,
                ...
                "received_amount_trend": {
                    "2022-07-31": 776950.85
                },
                "sent_amount_trend": {
                    "2022-07-31": 716483.35
                },
                "balance_amount_trend": {
                    "2022-07-31": 57584.3687772926
                },
                "business_label": 0,
                "initial_score": 327.0,
                "bank_score": 327.0,
                "score": 327.0,
                "bank_version": "v1",
                "limit": "[273394.0, 410091.0]"
            },
            "1y": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "6m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "3m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            },
            "1m": {
                "first_transaction_date": "2022-07-01T00:00:00",
                "last_transaction_date": "2022-07-29T00:00:00",
                "max_sent": 127715.0,
                "mean_sent": 3107.049134199134,
                "max_received": 113039.0,
                "avg_received": 3368.8132034632035,
                "total_received_amount": 778195.85,
                ...
            }
        },
        "created_at": "2025-06-20T12:00:58"
    }
}
```

{% endtab %}

{% tab title="404 when statement doesn't exist" %}

```json
{
    "status": 404,
    "message": "Statement not found"
}
```

{% endtab %}
{% endtabs %}


# Transactions Operations

Submit transactions data for credit scoring


# Submit Transactions

Submit transactions data for credit scoring

## Submit Transactions

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/transactions/upload`

This endpoint allows you to submit transaction data for credit scoring.

#### Headers

<table><thead><tr><th width="206">Name</th><th width="171">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication</td><td>String</td><td>Authentication token to track down who is emptying our stocks.</td></tr></tbody></table>

#### Request Body

<table><thead><tr><th>Name</th><th width="233">Type</th><th>Description</th></tr></thead><tbody><tr><td>transactions</td><td>String</td><td>A list of transaction objects</td></tr></tbody></table>

{% tabs %}
{% tab title="JSON Request" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong><strong>  "transactions": [
</strong>     { 
       "merchant_id": "P-CUST-2023-00083",
       "transaction_id": "P-SINV-2023-192927",
       "face_amount": 1943,
       "transaction_time": "2023-10-14 00:00:00",
       "other_details": {}
     },
     {
       "merchant_id": "P-CUST-2023-00084",
       "transaction_id": "P-SINV-2023-227940",
       "face_amount": 47504,
       "transaction_time": "2023-11-06 00:00:00",
       "other_details": {}
     },
     {...}
  ]
<strong>}
</strong></code></pre>

{% endtab %}

{% tab title="Response" %}

```javascript
{
    "status": 202,
    "message": "Transactions submitted successfully",
    "data": {
        "ref_id": "9e360d21-7601-4366-80a6-d8d4afffadc2"
    }
}
```

{% endtab %}
{% endtabs %}


# Fetch Score Results

Fetch transactions credit score results

## Fetch Score

<mark style="color:green;">`GET`</mark> `{{BASE_URL}}/api/v1/transactions/score?merchant_id=`M12345

This endpoint allows you to submit transaction data for credit scoring.

#### Headers

<table><thead><tr><th width="206">Name</th><th width="171">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication</td><td>String</td><td>Authentication token to track down who is emptying our stocks.</td></tr></tbody></table>

#### Request Parameters

<table><thead><tr><th>Name</th><th width="233">Type</th><th>Description</th></tr></thead><tbody><tr><td>merchant_id</td><td>String</td><td>ID of the merchant</td></tr></tbody></table>

{% tabs %}
{% tab title="Request" %}

<pre class="language-javascript"><code class="lang-javascript">{
<strong>  "merchant_id": "P-CUST-2023-00084"
</strong><strong>}
</strong></code></pre>

{% endtab %}

{% tab title="Response" %}

```javascript
{
  "status": 200,
  "message": "Transaction score data fetched successfully",
  "data": {
    "customer_id": 1001,
    "merchant_id": "M12345",
    "loan_type": "short_term",
    "principal_segment": "SME",

    // Order count
    "no_of_orders_1m": 15,
    "no_of_orders_3m": 45,
    "no_of_orders_6m": 120,

    // Total order amount
    "total_order_amount_1m": 20000.25,
    "total_order_amount_3m": 54000.45,
    "total_order_amount_6m": 150000.75,

    // Maximum order amount
    "max_order_amount_1m": 2500.0,
    "max_order_amount_3m": 4000.0,
    "max_order_amount_6m": 5000.0,

    // Minimum order amount
    "min_order_amount_1m": 350.0,
    "min_order_amount_3m": 300.0,
    "min_order_amount_6m": 250.0,

    // Number of unique products
    "no_unique_products_1m": 10,
    "no_unique_products_3m": 18,
    "no_unique_products_6m": 35,

    {...}

    "score_output": {
      "reason_code_1": "Low number of transactions",
      "reason_code_2": "Low frequency of transactions",
      "reason_code_3": "Customer inactive for a long period",
      "reason_code_4": "Low transaction volumes",
      "probability": "45.56",
      "grade": "GG",
      "credit_score": "412",
    },

    "fraud_output": {
      "transaction_risk_score": 68.45,
      "risk_grade": "High Risk",
      "reason_codes": {
        "code_1": "Low transaction count over the past 90 days",
        "code_2":
          "Irregular transaction frequency compared to historical patterns",
        "code_3":
          "Extended inactivity period detected (last transaction > 180 days)",
      },
      "alert_flag": "Red",
      "recommended_action": "Immediate manual review and enhanced due diligence",
    },
  },
};
```

{% endtab %}
{% endtabs %}


# Financial Education


# Fetch Modules

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/fe/program/modules?program_identifier=[program_id]`

This endpoint allows you to get free cakes.

#### Path Parameters

| Name                | Type   | Description             |
| ------------------- | ------ | ----------------------- |
| program\_identifier | string | Program Identifier UUID |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Modules successfully fetched",
    "data": [
        {
            "identifier": "31b2166c-dccf-4c92-a124-209c1d86c07c",
            "description": "Credit Scores & CRBs Tips",
            "more_details": "More Details about Module"
        },
        {
            "identifier": "3a45b50b-ca48-4616-9c5a-6f2568079304",
            "description": "General Financial Tips",
            "more_details": "More Details about Module"
        }
    ]
}

```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{
    "status": 404,
    "message": "Modules Not Found"
}

```

{% endtab %}
{% endtabs %}


# Fetch Websocket Conversaction

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/message/all?customerUuid=[customer_uuid]&sessionUuid=[session_uuid]`

This endpoint allows you to get free cakes.

#### Path Parameters

| Name | Type   | Description                                |
| ---- | ------ | ------------------------------------------ |
| id   | string | ID of the cake to get, for free of course. |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Messages successfully fetched",
    "data": [
        {
            "id": 888,
            "message": "Congratulations! You have successfully been enrolled to the Test Module Updated that aims to help you climb up the financial ladder. To start, please take this pre-quiz to gauge your level of knowledge before the training.\n Reply with 1 to start.",
            "session_uuid": "ea922437-0364-456d-a454-1ed530419292",
            "message_type": "SENT",
            "date_time": "15/04/2020 16:52"
        },
        {
            "id": 889,
            "message": "1",
            "session_uuid": "ea922437-0364-456d-a454-1ed530419292",
            "message_type": "RECEIVED",
            "date_time": "15/04/2020 16:56"
        }    ]
}


```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
```

{% endtab %}
{% endtabs %}


# Fetch Customer Session Summary

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/fe/customer/session/summary?customerUuid=[customer_uuid]&sessionUuid=[session_uuid]`

This endpoint allows you to get free cakes.

#### Path Parameters

| Name          | Type   | Description                                |
| ------------- | ------ | ------------------------------------------ |
| session\_uuid | string | ID of the cake to get, for free of course. |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Program session summary successfully fetched",
    "data": {
        "post_quiz_score": "0/2",
        "last_active_date": "",
        "program_name": "Test Prog",
        "module_uuid": "31b2166c-dccf-4c92-a124-209c1d86c07c",
        "module_name": "Credit Scores & CRBs Tips",
        "session_uuid": "4b697a1f-29f1-4d5a-af9d-5ead6ed74d77",
        "status": "Pending"
    }
}

```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
```

{% endtab %}
{% endtabs %}


# Fetch Customer Summary

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}  /api/v1/fe/customer/summary?customerUuid=[customer_uuid]`

This endpoint allows you to get free cakes.

#### Path Parameters

| Name           | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| customer\_uuid | string | ID of the cake to get, for free of course. |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Summary successfully fetched",
    "data": [
        {
            "session_uuid": "4b697a1f-29f1-4d5a-af9d-5ead6ed74d77",
            "status": "Pending",
            "program_name": "Test Prog",
            "last_active_date": "",
            "module_name": "Credit Scores & CRBs Tips",
            "module_uuid": "31b2166c-dccf-4c92-a124-209c1d86c07c",
             "post_quiz_score": "0/2"
        },
        {
            "session_uuid": "84b6df1d-fdc7-476d-957d-37270c5842f4",
            "status": "Pending",
            "program_name": "Test Prog",
            "last_active_date": "",
            "module_name": "Debt Management Tips",
            "module_uuid": "f65e16f2-f1e7-4482-8dd4-a103d793a3ac",
            "post_quiz_score": "0/2"
        }
    ]
}


```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
If a customer does not exist, response is as below:
{
    "status": 404,
    "message": "Customer not found"
}
If a customer exists but has no session, response is:
{
    "status": 404,
    "message": "Customer not enrolled to any module"
}

```

{% endtab %}
{% endtabs %}


# Fetch Program Summary

## Fetch Program Summary

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}  /api/v1/fe/customer/summary?customerUuid=[customer_uuid]`

This endpoint allows you to get free cakes.

#### Path Parameters

| Name           | Type   | Description                                |
| -------------- | ------ | ------------------------------------------ |
| customer\_uuid | string | ID of the cake to get, for free of course. |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Summary successfully fetched",
    "data": [
        {
            "session_uuid": "4b697a1f-29f1-4d5a-af9d-5ead6ed74d77",
            "status": "Pending",
            "program_name": "Test Prog",
            "last_active_date": "",
            "module_name": "Credit Scores & CRBs Tips",
            "module_uuid": "31b2166c-dccf-4c92-a124-209c1d86c07c",
             "post_quiz_score": "0/2"
        },
        {
            "session_uuid": "84b6df1d-fdc7-476d-957d-37270c5842f4",
            "status": "Pending",
            "program_name": "Test Prog",
            "last_active_date": "",
            "module_name": "Debt Management Tips",
            "module_uuid": "f65e16f2-f1e7-4482-8dd4-a103d793a3ac",
            "post_quiz_score": "0/2"
        }
    ]
}

```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{    "message": "Ain't no cake like that."}
```

{% endtab %}
{% endtabs %}


# Customer Subscription

## Customer Subscription

<mark style="color:green;">`POST`</mark> `{{BASE_URL}}/api/v1/fe/program/customer/add`

This endpoint allows you to get free cakes.

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{
    "status": 200,
    "message": "Session created successfully",
    "data": {
        "customer_uuid": "508fb56e-9578-4b99-83b6-ebff46e2db30",
        "session_uuid": "7ba802b0-4ac8-4288-8047-dad3046ac738"
    }
}

```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{    "message": "Ain't no cake like that."}
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Request Body" %}

```
{
    "program_identifier": 49,
    "customer_uuid": "508fb56e-9578-4b99-83b6-ebff46e2db30",
    "module": "1ea7759a-6d49-488e-b8df-364f720707d8"
}

```

{% endtab %}
{% endtabs %}


# Subscribe to Websocket

## Get Cakes

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/ws`

This endpoint allows you to get free cakes.

#### Query Parameters

| Name       | Type   | Description              |
| ---------- | ------ | ------------------------ |
| identifier | string | Customer Identifier UUID |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{    "name": "Cake's name",    "recipe": "Cake's recipe name",    "cake": "Binary cake"}
```

{% endtab %}

{% tab title="404 Could not find a cake matching this query." %}

```
{    "message": "Ain't no cake like that."}
```

{% endtab %}
{% endtabs %}


# Elimiza


# Courses


# Fetch Courses

Returns a list of all published courses with user-specific information

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses`

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Courses retrieved successfully",
    "data": [
        {
            "id": 9,
            "title": "Understanding loans",
            "is_free": true,
            "price": 0.0,
            "description": "<div data-oe-version=\"1.2\">Learn how borrowing money from Pezesha can help your business grow</div>",
            "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQE…..",
            "users_enrolled": 101,
            "likes_count": 10,
            "rating": 0.0,
            "completion_status": "in_progress",
            "is_liked": true,
            "payment_status": "free",
            "can_access": true,
            "payment_message": "This course is free",
            "payment_id": null
        }
 ]
}
```

{% endtab %}

{% tab title="401 Authentication Failed" %}

```json
{
  "status": 401,
  "response_code": 0,
  "success": false,
  "errors": [
    "No token provided"
  ],
  "message": "No token, Authorization denied"
}
```

{% endtab %}
{% endtabs %}


# Fetch Course Details

Fetches details of a given course

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}`

#### Path Parameters

| Name       | Type    | Description             |
| ---------- | ------- | ----------------------- |
| course\_id | integer | ID of the course to get |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Course retrieved successfully",
    "data": {
        "welcome": "Welcome to Receiving your loan funds",
        "title": "Receiving your loan funds",
        "is_free": false,
        "price": 100.0,
        "short_description": "<div data-oe-version=\"1.2\">Learn when and how you'll get your money \n</div>",
        "users_enrolled": 45,
        "likes_count": 1,
        "rating": 0.0,
        "ratings_count": 0,
        "description": "<div data-oe-version=\"1.2\">Learn when and how you'll get your money \n</div>",
        "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgA……",
        "lessons_preview": [
            {
                "id": 53,
                "title": "Receive funds",
                "thumbnail": null,
                "lesson_progress_status": "not_started",
                "quiz_progress_status": "not_started"
            },
            {
                "id": 54,
                "title": "Fund receipt concerns",
                "thumbnail": null,
                "lesson_progress_status": "not_started",
                "quiz_progress_status": "not_started"
            }
        ],
        "is_liked": false,
        "has_access": false,
        "payment_status": "unpaid",
        "can_access": false,
        "payment_message": "Payment required to access this course",
        "payment_id": null,
        "completion_status": "not_started"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course not found"
}
```

{% endtab %}
{% endtabs %}


# Like a Course

This API allows you to like a given course

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}/like`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Course liked successfully",
    "data": {
        "message": "Course liked successfully"
    }
}

```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course not found"
}
```

{% endtab %}
{% endtabs %}


# Unlike a Course

This API allows you to unlike a given course

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}/dislike`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Headers

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Course disliked successfully",
    "data": {
        "message": "Course disliked successfully"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course not found"
}
```

{% endtab %}
{% endtabs %}


# Rate a Course

This API allows you to rate a given course

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}/rate`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Headers

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Course rated successfully",
    "data": {
        "message": "Course rated successfully"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course not found"
}
```

{% endtab %}
{% endtabs %}


# Course Progress

This API allows you get a given course's progress

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}/progress`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Headers

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Progress retrieved",
    "data": {
        "completed": 0,
        "total": 2,
        "percentage": 0.0,
        "message": "Completed 0/2 lessons",
        "lessons": [
            {
                "lesson_id": 53,
                "title": "Receive funds",
                "status": "not_started",
                "quiz_status": "not_started"
            },
            {
                "lesson_id": 54,
                "title": "Fund receipt concerns",
                "status": "not_started",
                "quiz_status": "not_started"
            }
        ],
        "course_status": "not_started"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course not found"
}
```

{% endtab %}
{% endtabs %}


# Lessons


# Fetch Lessons

Returns a list of all lessons for a given course

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{course_id}/lessons`

#### Path Parameters

| Name       | Type    | Description      |
| ---------- | ------- | ---------------- |
| course\_id | integer | ID of the course |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": 200,
  "response_code": 0,
  "success": true,
  "errors": [],
  "message": "Lessons retrieved successfully",
  "data": [
    {
      "id": 123,
      "course_id": 45,
      "title": "Introduction to Financial Planning",
      "slide_type": "video",
      "content": "https://youtube.com/watch?v=example",
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "learning_outcomes": [
        "Understand basic financial concepts"
      ],
      "completed": false,
      "status": "not_started"
    },
    {
      "id": 124,
      "course_id": 45,
      "title": "Creating Your Budget",
      "slide_type": "document",
      "content": "UERGLTEuNA0KJcOkw4zDqcS9...",
      "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
      "learning_outcomes": [
        "Create a personal budget"
      ],
      "completed": true,
      "status": "completed"
    }
  ]
}
```

{% endtab %}

{% tab title="401 Authentication Failed" %}

```json
{
  "status": 401,
  "response_code": 0,
  "success": false,
  "errors": [
    "No token provided"
  ],
  "message": "No token, Authorization denied"
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Course Not Found"
}
```

{% endtab %}
{% endtabs %}


# Fetch Lesson Details

Fetches details of a given lesson

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/lessons/{lesson_id}`

#### Path Parameters

| Name       | Type    | Description             |
| ---------- | ------- | ----------------------- |
| lesson\_id | integer | ID of the lesson to get |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": 200,
  "response_code": 0,
  "success": true,
  "errors": [],
  "message": "Lesson retrieved successfully",
  "data": {
    "id": 123,
    "course_id": 45,
    "title": "Introduction to Financial Planning",
    "slide_type": "video",
    "description": "Learn the basics of financial planning and budgeting",
    "content": "https://youtube.com/watch?v=example",
    "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...",
    "learning_outcomes": [
      "Understand basic financial concepts",
      "Create a personal budget",
      "Set financial goals"
    ],
    "completed": false,
    "status": "not_started"
  }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson not found"
}
```

{% endtab %}
{% endtabs %}


# Start a Lesson

This API allows you to start a lesson

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{lesson_id}/start`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Request Body

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| phone\_number | string | User phone number |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Lesson started successfully",
    "data": {
        "message": "Lesson started successfully",
        "status": "in_progress"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson not found"
}
```

{% endtab %}
{% endtabs %}

#### Start Lesson Request

{% tabs %}
{% tab title="Request Body" %}

```json
{
    "phone_number": "0700112233"
}
```

{% endtab %}
{% endtabs %}


# Complete a Lesson

This API allows you to complete a lesson

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/courses/{lesson_id}/complete`

#### Path Parameters

| Name       | Type    | Description              |
| ---------- | ------- | ------------------------ |
| course\_id | integer | ID of the course to like |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Lesson completed successfully",
    "data": {
        "message": "Lesson completed successfully",
        "status": "completed"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson not found"
}
```

{% endtab %}
{% endtabs %}


# Quiz


# Start Quiz

Allows user to start a quiz

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/lessons/{lesson_id}/quiz/start`

#### Path Parameters

| Name       | Type    | Description      |
| ---------- | ------- | ---------------- |
| lesson\_id | integer | ID of the lesson |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Quiz started",
    "data": {
        "message": "Quiz has started"
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson Not Found"
}
```

{% endtab %}
{% endtabs %}


# Get Quiz Questions

Fetches questions for a given quiz

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/lessons/{lesson_id}/quiz/questions`

#### Path Parameters

| Name       | Type    | Description             |
| ---------- | ------- | ----------------------- |
| lesson\_id | integer | ID of the lesson to get |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": 200,
  "response_code": 0,
  "success": true,
  "errors": [],
  "message": "Questions retrieved",
  "data": {
    "total_questions": 5,
    "questions": [
      {
        "question_number": 1,
        "question_id": 46,
        "text": " What is one key advantage of Pezesha's fast and simple process?",
        "options": [
          {
            "id": 170,
            "text": "It requires extensive documentation."
          },
          {
            "id": 171,
            "text": "It provides quick approval decisions and rapid money transfer to M-PESA."
          }
        ]
      },
      {
        "question_number": 2,
        "question_id": 47,
        "text": "Which of the following is true about Pezesha's collateral requirements?",
        "options": [
          {
            "id": 174,
            "text": "You must provide multiple forms of collateral."
          },
          {
            "id": 175,
            "text": "Collateral is optional but preferred."
          }
        ]
      }
    ]
  }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson not found"
}
```

{% endtab %}
{% endtabs %}


# Submit Quiz Answers

This API allows you to submit answers for a quiz

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/lessons/{lesson_id}/quiz/submit`

#### Path Parameters

| Name       | Type    | Description |
| ---------- | ------- | ----------- |
| lesson\_id | integer | Lesson id   |

#### Request Body

| Name         | Type    | Description        |
| ------------ | ------- | ------------------ |
| question\_id | integer | ID of the question |
| answer\_id   | integer | ID of the answer   |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Answer submitted",
    "data": {
        "is_correct": false,
        "feedback": "Wrong. Correct answer: It provides quick approval decisions and rapid money transfer to M-PESA."
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Lesson not found"
}
```

{% endtab %}
{% endtabs %}

#### Start Lesson Request

{% tabs %}
{% tab title="Request Body" %}

```json
{
    "phone_number": "0700112233"
}
```

{% endtab %}
{% endtabs %}


# Get Quiz Results

This API allows you to get results for a given quiz

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/lessons/{lesson_id}/quiz/results`

#### Path Parameters

| Name       | Type    | Description      |
| ---------- | ------- | ---------------- |
| lesson\_id | integer | ID of the lesson |

#### Headers

<table><thead><tr><th>Name</th><th width="249">Type</th><th>Description</th></tr></thead><tbody><tr><td>Authentication</td><td>string</td><td>Authentication token to track down who is emptying our stocks.</td></tr></tbody></table>

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Course liked successfully",
    "data": {
        "message": "Course liked successfully"
    }
}

```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Quiz results retrieved",
    "data": {
        "score": "You got 0/5 correct",
        "results": [
            {
                "question": " What is one key advantage of Pezesha's fast and simple process?",
                "your_answer": "It requires extensive documentation.",
                "is_correct": false,
                "correct_answer": "It provides quick approval decisions and rapid money transfer to M-PESA."
            },
            {
                "question": "Which of the following is true about Pezesha's collateral requirements?",
                "your_answer": "No answer",
                "is_correct": null,
                "correct_answer": "Collateral is not required since loans are based on business performance."
            },
            {
                "question": "How does Pezesha ensure fairness in its loan process?",
                "your_answer": "No answer",
                "is_correct": null,
                "correct_answer": "Through straightforward interest calculation and flexible payment schedules."
            },
            {
                "question": "What additional business support does Pezesha offer?",
                "your_answer": "No answer",
                "is_correct": null,
                "correct_answer": "Free financial education and convenient customer support"
            },
            {
                "question": "Which visual is used to compare Pezesha's document requirements with those of traditional banks?",
                "your_answer": "No answer",
                "is_correct": null,
                "correct_answer": "A comparison chart"
            }
        ]
    }
}
```

{% endtab %}
{% endtabs %}


# Subscriptions


# Pricing Options

Allows user to get pricing options

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/subscriptions/pricing`

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": 200,
  "response_code": 0,
  "success": true,
  "errors": [],
  "message": "Pricing retrieved successfully",
  "data": {
    "individual_courses": [
      {
        "id": 45,
        "name": "Personal Finance Fundamentals",
        "price": 2500.0,
        "description": "Master the basics of personal finance"
      },
      {
        "id": 46,
        "name": "Investment Strategies",
        "price": 3500.0,
        "description": "Learn advanced investment techniques"
      },
      {
        "id": 47,
        "name": "Business Finance",
        "price": 4000.0,
        "description": "Financial management for entrepreneurs"
      }
    ],
    "bundle": {
      "price": 10000.0,
      "course_count": 3,
      "course_ids": [45, 46, 47],
      "course_names": [
        "Personal Finance Fundamentals",
        "Investment Strategies", 
        "Business Finance"
      ],
      "description": "Get access to all 3 courses"
    },
    "user_owned_count": 0,
    "total_paid_courses": 3,
    "available_courses_count": 3
  }
}
```

{% endtab %}

{% tab title="401 Authentication Failed" %}

```json
{
  "status": 401,
  "response_code": 0,
  "success": false,
  "errors": [
    "No token provided"
  ],
  "message": "No token, Authorization denied"
}
```

{% endtab %}
{% endtabs %}


# User Subscriptions

Fetches user subscriptions

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/subscriptions/user-subscriptions`

#### Path Parameters

| Name       | Type    | Description             |
| ---------- | ------- | ----------------------- |
| lesson\_id | integer | ID of the lesson to get |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
  "status": 200,
  "response_code": 0,
  "success": true,
  "errors": [],
  "message": "Subscriptions retrieved successfully",
  "data": [
    {
      "id": 301,
      "type": "single",
      "amount_paid": 2500.0,
      "original_price": 2500.0,
      "created_date": "2024-03-15T10:30:00.000Z",
      "status": "active",
      "courses": [
        {
          "id": 45,
          "name": "Personal Finance Fundamentals",
          "price": 2500.0,
          "description": "Master the basics of personal finance"
        }
      ]
    },
    {
      "id": 302,
      "type": "bundle",
      "amount_paid": 7500.0,
      "original_price": 7500.0,
      "created_date": "2024-03-20T14:15:00.000Z",
      "status": "pending",
      "courses": [
        {
          "id": 46,
          "name": "Investment Strategies",
          "price": 3500.0,
          "description": "Learn advanced investment techniques"
        },
        {
          "id": 47,
          "name": "Business Finance",
          "price": 4000.0,
          "description": "Financial management for entrepreneurs"
        }
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}


# Payments


# Make Payment

Allows user to initiate payment

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/payments/stk-push`

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

#### Request Body

| Name                  | Type             | Description                       |
| --------------------- | ---------------- | --------------------------------- |
| paying\_phone\_number | string           | Phone number used to make payment |
| amount                | integer          | Amount to pay                     |
| course\_ids           | list of integers | A list of course ids to pay for   |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "STK push initiated successfully",
    "data": {
        "payment_id": 45,
        "amount": 1.0,
        "phone_number": "254742654803",
        "status": "pending",
        "message": "Success. Request accepted for processing",
        "merchant_request_id": "68b7-458a-a02b-cfbe240f00fe383201"
    }
}
```

{% endtab %}

{% tab title="401 Authentication Failed" %}

```json
{
  "status": 401,
  "response_code": 0,
  "success": false,
  "errors": [
    "No token provided"
  ],
  "message": "No token, Authorization denied"
}
```

{% endtab %}
{% endtabs %}


# Payment Status

Fetches user subscriptions

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/payments/{payment_id}/status`

#### Path Parameters

| Name        | Type    | Description       |
| ----------- | ------- | ----------------- |
| payment\_id | integer | ID of the payment |

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 OK" %}

```json
{
    "status": 200,
    "response_code": 0,
    "success": true,
    "errors": [],
    "message": "Payment status retrieved",
    "data": {
        "id": 46,
        "amount": 2.0,
        "status": "pending",
        "mpesa_reference": false,
        "subscription_type": "bundle",
        "course_ids": [
            11,
            12
        ],
        "payment_date": null,
        "failure_reason": false
    }
}
```

{% endtab %}

{% tab title="404 Not Found" %}

```json
{
    "status": 404,
    "message": "Payment not found"
}
```

{% endtab %}
{% endtabs %}


# Billing Operations


# Account Balance

## Get account balance

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/account/balance`

This endpoint allows you to get your account balance

#### Headers

| Name                                             | Type   | Description          |
| ------------------------------------------------ | ------ | -------------------- |
| Authentication<mark style="color:red;">\*</mark> | String | Authentication token |

{% tabs %}
{% tab title="200 Balance successfully retrieved." %}

```
{
    "status": 200,
    "message": "Account balance successfully fetched",
    "data": {
        "amount": 5763
    }
}
```

{% endtab %}
{% endtabs %}


# Topups

## Get Account Topups made

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/account/topups/all`

This endpoint allows you to get all the account topups done.

#### Headers

| Name           | Type   | Description          |
| -------------- | ------ | -------------------- |
| Authentication | string | Authentication token |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```javascript
{
   "status":200,
   "message":"Account topup successfully fetched",
   "data":{
      "amount":0.0
   }
}
```

{% endtab %}
{% endtabs %}


# Account Usage

## Account Usage

<mark style="color:blue;">`GET`</mark> `{{BASE_URL}}/api/v1/account/usage`

This endpoint allows you to get the API usage for your account

#### Headers

| Name           | Type   | Description                                                    |
| -------------- | ------ | -------------------------------------------------------------- |
| Authentication | string | Authentication token to track down who is emptying our stocks. |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```javascript
{
   "status":200,
   "message":"Api usage successfully fetched",
   "data":{
      "amount":0.0
   }
}
```

{% endtab %}
{% endtabs %}