Upload Statement (Extraction)

Upload Bank statement for analysis and credit scoring

Upload Bank Statements

POST {{BASE_URL}}/api/v1/statements/bank/upload

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

Headers

Name	Type	Description
Authentication*	string	Authentication token to track down API usage.

Request Body

Name	Type	Description
national_id*	String	User's national ID
file*	String	Base64 encoded file string
file_name*	String	Renamed filename using user national id i.e 34213456.pdf
callback_url*	String	Where to send result
bank*	String	Statement bank (Lowercase: im, equity, sbm, kcb, absa, e.tc)

200 Statement saved successfully

{
    "status": 202,
    "message": "Statement saved successfully. Extraction process initiated",
    "data": {
        "national_id": "27365875",
        "bank": "absa",
        "reference_id": "bdcb2d95-ad53-4245-8af7-f745ae7d4f33",
        "file_name": "27365875.pdf"
    }
}

400 In case of error

{
    "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"
    ]
}

Statement upload request Example

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

Statement Callback Response Example

{
    "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"
    }
}