> For the complete documentation index, see [llms.txt](https://docs.patascore.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.patascore.com/bank-operations/upload-statement-extraction.md).

# Upload Statement (Extraction)

## 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"
    }
}
```