> Docs index: https://convertextrato.com/llms.txt

# Convert Statement API


The Convert Statement API turns bank statement PDFs and images into structured JSON: the statement header and one row per transaction. It is the same extraction the web app runs.

The API is asynchronous. You upload files and get a Job back at once. You then poll the Job until it finishes.

## Base URL

```
https://energized-butterfly-12.convex.site/v1
```

Every request uses HTTPS and authenticates with an API key. Responses are JSON.

## Quickstart

### 1. Create an API key

An API key needs the **Starter** or **Professional** plan. The owner or an admin of the account creates keys on the [API keys page](https://convertextrato.com/admin/api-keys).

Choose **Read and write** access to upload files. Copy the key when it appears.

> The key is shown only once. Store it in a secret manager or an environment variable. Anyone with the key can spend your plan's pages.

```bash
export CONVERT_API_KEY="bsk_live_..."
```

### 2. Upload a statement

```bash
curl https://energized-butterfly-12.convex.site/v1/jobs \
  -H "Authorization: Bearer $CONVERT_API_KEY" \
  -F "files=@statement.pdf" \
  -F "mode=smart"
```

The API answers `202 Accepted` with a pending Job:

```json
{
  "id": "jn7craq7xc3qjq1knfzy5612f98gqnmh",
  "status": "pending",
  "createdAt": "2026-10-21T12:51:02.816Z",
  "files": [
    {
      "id": "jd72x05815g515gkv5wrwemye58gp7g5",
      "name": "statement.pdf",
      "status": "pending",
      "pageCount": 1,
      "mode": "smart",
      "error": null
    }
  ]
}
```

### 3. Poll until the Job finishes

```bash
curl https://energized-butterfly-12.convex.site/v1/jobs/jn7craq7xc3qjq1knfzy5612f98gqnmh \
  -H "Authorization: Bearer $CONVERT_API_KEY"
```

Poll every 5 seconds until `status` is `processed` or `failed`. Each extracted file then carries a `statement` and its `transactions`.

```json
{
  "id": "jn7craq7xc3qjq1knfzy5612f98gqnmh",
  "status": "processed",
  "createdAt": "2026-10-21T12:51:02.816Z",
  "files": [
    {
      "id": "jd72x05815g515gkv5wrwemye58gp7g5",
      "name": "statement.pdf",
      "status": "extracted",
      "pageCount": 1,
      "mode": "smart",
      "error": null,
      "statement": {
        "bankName": "E2E Test Bank",
        "accountNumber": "****56",
        "currency": "USD",
        "startDate": "2026-09-01T00:00:00Z",
        "endDate": "2026-09-30T00:00:00Z",
        "openingBalance": 1000,
        "closingBalance": 2789.6
      },
      "transactions": [
        {
          "date": "2026-09-02T00:00:00Z",
          "description": "Salary ACME Corp",
          "amount": 2500,
          "balance": 3500,
          "type": "Deposit",
          "category": "Salary",
          "reference": null
        }
      ]
    }
  ]
}
```

The `statement` above is shortened. See [Jobs](/developers/jobs) for every field.

## Next steps

- [Authentication](/developers/authentication): API keys, permissions, plans and rate limits.
- [Jobs](/developers/jobs): every endpoint and the full Job object.
- [Errors](/developers/errors): the error format and every error code.
- [MCP server](/developers/mcp): connect AI agents such as Claude Code, Cursor, VS Code and Codex.

Each page is also available as Markdown: add `.md` to its URL. [llms.txt](/llms.txt) lists every page for AI agents.