On this page
Read bank statements only with Vector
Read a PDF bank statement without creating an application. Vector checks that the statement belongs to the account holder you name, then returns the account details and transactions.
Use this when you need statement data without an underwriting decision. To assess an applicant, submit an application instead.
Upload a statement#
POST /api/v1/statement-reads
Requires the decisions:create scope. Statement reads accept PDF files only.
| Field | Description |
|---|---|
file | Required. The PDF statement. File limit of 20 MiB. |
accountHolderName | Required. The person or business the statement should belong to. |
accountHolderType | individual (default) or business. |
accountNumber | Optional. The 10-digit account number the statement should show. |
password | Optional. The PDF’s password, if it’s protected. |
reference | Optional. Your reference, unique per environment. Send the same reference to retry safely; Vector returns the existing read. |
curl --request POST "$VECTOR_BASE_URL/api/v1/statement-reads" \
--header "Authorization: Bearer $VECTOR_API_KEY" \
--header 'Accept: application/json' \
--form '[email protected]' \
--form 'accountHolderName=Amara Okafor' \
--form 'accountNumber=0000000001' \
--form 'reference=read-demo-001'Vector returns 202 Accepted with the statement read id and status: "pending". Keep the PDF and its password out of logs and error trackers.
Retrieve a statement read#
GET /api/v1/statement-reads/{id}
curl "$VECTOR_BASE_URL/api/v1/statement-reads/$STATEMENT_READ_ID" \
--header "Authorization: Bearer $VECTOR_API_KEY" \
--header 'Accept: application/json'Fetch until status is completed or failed, or wait for the statement_read.completed or statement_read.failed webhook.
{
"id": "STATEMENT_READ_ID",
"reference": "read-demo-001",
"status": "completed",
"failure": null,
"accounts": [
{
"accountInfo": {
"name": "AMARA CHIOMA OKAFOR",
"accountNumber": "0000000001",
"type": "wallet",
"balance": 5808718,
"currency": "NGN",
"institution": { "name": "Yana Test Bank" }
},
"meta": {
"statement_period": { "from": "2026-08-01", "to": "2026-10-31" },
"opening_balance": 100000,
"closing_balance": 5808718
},
"transactions": [
{
"id": "txn_4f0c2a9b1d7e6a3c5b8e9f01",
"date": "2026-08-03T00:00:00.000Z",
"type": "debit",
"amount": 110000,
"balance": 5990000,
"currency": "NGN",
"narration": "Money sent"
}
]
}
]
}Amounts and balances are in kobo. accountInfo.balance is the statement’s closing balance. accounts has one entry per account read from the PDF.
Data retention#
Vector deletes the uploaded PDF after 30 days. Extracted data is cleared after 2 years, and the statement read then returns status: "expired".
Test environment#
With a test key, use a Yana test statement.
Responses#
| Status | Meaning |
|---|---|
202 | Read accepted, status: "pending" |
200 | Read returned. This is what GET returns, and also what you get when you resend a reference that already exists |
400 | VALIDATION_ERROR: see error.details.fields |
401 | INVALID_API_KEY or REVOKED_API_KEY |
402 | SUBSCRIPTION_INACTIVE |
403 | INSUFFICIENT_PERMISSIONS |
404 | NOT_FOUND |
422 | PDF_PASSWORD_REQUIRED, PDF_PASSWORD_INCORRECT or PDF_UNREADABLE |
429 | RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED |
503 | PROCESSING_UNAVAILABLE or BILLING_UNAVAILABLE. Retry with the same reference |
Errors use the standard error format. Problems with the statement's contents aren't HTTP errors. The upload returns 202, and the read ends with status: "failed" and a failure.code, for example STATEMENT_NAME_MISMATCH, STATEMENT_ACCOUNT_MISMATCH, PDF_UNRECONCILED, PDF_NO_TRANSACTIONS or TEST_STATEMENT_UNSUPPORTED.
What counts as a request#
A read counts as one request once it's accepted with 202, including reads that later fail. Requests turned down at upload aren't counted: errors from 400 to 429, and a resent reference.
Error codes#
These are returned when you upload:
| Code | Required action |
|---|---|
VALIDATION_ERROR | Fix the fields in error.details.fields. Only PDFs are accepted. |
PDF_PASSWORD_REQUIRED | Send the PDF’s password in password. |
PDF_PASSWORD_INCORRECT | Check the password and resubmit. |
PDF_UNREADABLE | Upload a readable copy. |
These appear in failure.code when status is failed:
| Code | Required action |
|---|---|
STATEMENT_NAME_MISMATCH | Upload the named holder’s statement, or correct accountHolderName. |
STATEMENT_NAME_UNAVAILABLE | Upload a statement that shows the account holder’s name. |
STATEMENT_ACCOUNT_MISMATCH | Upload the statement for accountNumber, or correct the number. |
STATEMENT_ACCOUNT_NUMBER_UNAVAILABLE | Upload a statement that shows the account number, or leave out accountNumber. |
PDF_ACCOUNT_SELECTION_REQUIRED | The PDF has several accounts. Send accountNumber. |
PDF_NO_TRANSACTIONS, PDF_UNRECONCILED | Upload a complete original export. |
TEST_STATEMENT_UNSUPPORTED | In the test environment, use a Yana test statement. Use your live key for other statements. |
PROCESSING_UNAVAILABLE | Upload again, or contact support with the statement read ID. |
A failed read isn’t retried. Upload a corrected statement as a new statement read.