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.

FieldDescription
fileRequired. The PDF statement. File limit of 20 MiB.
accountHolderNameRequired. The person or business the statement should belong to.
accountHolderTypeindividual (default) or business.
accountNumberOptional. The 10-digit account number the statement should show.
passwordOptional. The PDF’s password, if it’s protected.
referenceOptional. Your reference, unique per environment. Send the same reference to retry safely; Vector returns the existing read.
bash
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}

bash
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.

json
{
  "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#

StatusMeaning
202Read accepted, status: "pending"
200Read returned. This is what GET returns, and also what you get when you resend a reference that already exists
400VALIDATION_ERROR: see error.details.fields
401INVALID_API_KEY or REVOKED_API_KEY
402SUBSCRIPTION_INACTIVE
403INSUFFICIENT_PERMISSIONS
404NOT_FOUND
422PDF_PASSWORD_REQUIRED, PDF_PASSWORD_INCORRECT or PDF_UNREADABLE
429RATE_LIMIT_EXCEEDED or QUOTA_EXCEEDED
503PROCESSING_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:

CodeRequired action
VALIDATION_ERRORFix the fields in error.details.fields. Only PDFs are accepted.
PDF_PASSWORD_REQUIREDSend the PDF’s password in password.
PDF_PASSWORD_INCORRECTCheck the password and resubmit.
PDF_UNREADABLEUpload a readable copy.

These appear in failure.code when status is failed:

CodeRequired action
STATEMENT_NAME_MISMATCHUpload the named holder’s statement, or correct accountHolderName.
STATEMENT_NAME_UNAVAILABLEUpload a statement that shows the account holder’s name.
STATEMENT_ACCOUNT_MISMATCHUpload the statement for accountNumber, or correct the number.
STATEMENT_ACCOUNT_NUMBER_UNAVAILABLEUpload a statement that shows the account number, or leave out accountNumber.
PDF_ACCOUNT_SELECTION_REQUIREDThe PDF has several accounts. Send accountNumber.
PDF_NO_TRANSACTIONS, PDF_UNRECONCILEDUpload a complete original export.
TEST_STATEMENT_UNSUPPORTEDIn the test environment, use a Yana test statement. Use your live key for other statements.
PROCESSING_UNAVAILABLEUpload again, or contact support with the statement read ID.

A failed read isn’t retried. Upload a corrected statement as a new statement read.