canonical: https://jentic.com/apis/pivotbank.app/pivotbank

# Pivotbank App PivotBank API

The PivotBank API converts a digital bank statement PDF into structured JSON transactions, each with its date, description, money out, money in, running balance, and the page it was printed on. Every reading is checked against the statement's own running balances: a reconciliation block reports whether opening balance plus every row lands exactly on the closing balance, and each transaction carries its own check value of ok, gap, or uncovered. An Idempotency-Key header lets a retry with the same file return the first answer without spending pages again, and the X-Pages-Left response header reports what remains of the plan's monthly page allowance.

## For AI agents

Turn a text-layer bank statement PDF into a JSON list of transactions with balances, page numbers, and a reconciliation verdict that says whether the reading balances. Includes an open index operation describing the endpoints and auth walkthrough.

## Scope

Does not handle scanned statement images, live bank account connections, or ledger posting. Use for converting digital bank statement PDFs into reconciled transactions only.

## Capabilities

- Convert a digital bank statement PDF, sent as multipart form data or a raw application/pdf body, into a JSON list of transactions in printed order
- Return the bank name, account number, statement period, page count, and transaction count read from the statement
- Gate on the reconciliation verdict, which compares opening balance plus every credit minus every debit against the printed closing balance
- Flag individual rows whose running balance does not follow from the row before, using each transaction's check value
- Retry a conversion safely with an Idempotency-Key so a repeated upload of the same file is not charged twice
- Read the X-Pages-Left header after each call to track the remaining monthly page allowance

## Use cases

### Agent-Driven Statement Extraction via Jentic

An AI agent handling bookkeeping or loan paperwork receives bank statements as PDFs and needs the rows as data. Through Jentic the agent calls the PivotBank convert operation with the PDF, reads back every transaction with debit, credit, and balance, and only passes the result on when the reconciliation verdict is true, sending mismatched statements to a person for review instead.

Example prompt: Upload the March statement PDF to the convert operation, confirm reconciliation.verified is true, and return the list of transactions with a debit over 500

### Bookkeeping Import from Statement PDFs

Accountants who receive statements as PDFs from clients convert each file into rows of date, description, money out, money in, and running balance, ready to import into an accounting ledger. Because each row carries its own check value, rows marked gap can be inspected before import instead of discovering a missing transaction at month end.

Example prompt: Convert a client's quarterly statement PDF, list every transaction whose check value is gap, and report the reconciliation difference

### Income and Affordability Checks

Lenders and landlords reviewing an applicant's statements need totals they can trust. The PivotBank API returns totalIn and totalOut alongside opening and closing balances, so an agent can summarise money in and money out for the period and refuse to summarise a statement whose reconciliation status is mismatch or unavailable.

Example prompt: Convert an applicant's statement, confirm the reconciliation status is ok, and report totalIn, totalOut, and the statement period

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v1/convert` | Convert a bank statement PDF to transactions |
| GET | `/api/v1/` | Read the API index and auth walkthrough |

## Key resources

- **Statements** — Convert a bank statement PDF into bank name, account number, period, page count, reconciliation, and transactions.
- **Transactions** — Each row's date, description, debit, credit, running balance, page, and check value.
- **Reconciliation** — The verified flag, status, opening and closing balances, expected closing, difference, and totals in and out.
- **Meta** — An open index of the endpoints, spec, and auth walkthrough as JSON.

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 64 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 74 / 100
  - Developer Experience & Jentic Compatibility: 66 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 50 / 100
- **View full report:** https://jentic.com/apis/pivotbank.app/pivotbank/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring PivotBank by hand means creating a Pro account API key, sending it as a bearer token, uploading PDFs as multipart or raw bodies, and managing Idempotency-Key retries yourself. Through Jentic you install once, import PivotBank from the API Directory, store the key once, and your agent converts statements.
- **Permission scoping:** PivotBank exposes a single convert operation plus an open index, with no resource id in the path, so rules bound which operations your agent may call rather than which statement. You choose the operations it may call, so a rule can allow conversion alone.
- **Credential handling:** Your PivotBank API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'convert a bank statement PDF' or 'extract statement transactions', and Jentic returns the matching PivotBank operation with its input schema so the agent calls the right endpoint without reading the reference docs.

## Related APIs

- **Veryfi** — Veryfi extracts data from receipts, invoices, and bank statements with OCR; PivotBank focuses on text-layer statements with balance reconciliation.
- **Mindee** — Mindee offers general document parsing models; PivotBank returns statement transactions checked against running balances.
- **Plaid** — Plaid pulls transactions directly from linked bank accounts; PivotBank reads them from statement PDFs when no account link is available.
- **Xero Accounting** — Xero holds the ledger; PivotBank supplies the statement transactions to import into it.

## FAQ

### What authentication does the PivotBank API use?

Per its OpenAPI spec, the PivotBank API uses bearer authentication: send an API key of the form pvb_live_... in an Authorization: Bearer header, and the spec notes an x-api-key header is also accepted. Keys are created on the API keys page of your PivotBank account, are shown once, and must belong to a Pro account. The convert operation needs the key, while the index operation at `/api/v1`/ is open. Through Jentic the key is stored encrypted on your own instance and injected at call time.

### Is there a PivotBank MCP server?

You don't need an MCP server to give your agent PivotBank. Jentic connects it directly from the API Directory: import PivotBank, store your API key once, and your agent can convert statements straight away. Operations are discovered on demand, so no extra server's tool definitions sit in your agent's context.

### Can I limit what my agent is allowed to do with the PivotBank API?

Yes. Write a rule that allows only the convertStatement operation, so the agent can turn statement PDFs into transactions and nothing else, and every call it makes is logged. The open index operation can stay out of the rule if the agent has no need to read it.

### Does the PivotBank API work with scanned statements?

No. The convert operation reads digital bank statements that have a text layer, up to 15 MB per file, and the spec states that scanned statements are not supported on this endpoint. A file that is not a readable PDF returns a 422 with the code unparseable and is not charged.

### What are the rate limits for the PivotBank API?

The PivotBank API is metered by pages rather than by request count. Each conversion spends the statement's page count from the plan's monthly allowance, and every response carries X-Pages-Left plus RateLimit-Limit, RateLimit-Remaining, and RateLimit-Policy headers describing that allowance. The spec does not publish fixed numbers for each plan; check https://pivotbank.app for current plan allowances.

### How do I convert a bank statement with the PivotBank API through Jentic?

Search Jentic for an intent like 'convert a bank statement PDF to transactions', import PivotBank, and store your API key once. Your agent then calls the convert operation at `/api/v1/convert` with the PDF and an Idempotency-Key, and reads the reconciliation verdict before using the rows. To run it on your own infrastructure, install Jentic One from its GitHub repo.