> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ledgersyncappv2.com/llms.txt
> Use this file to discover all available pages before exploring further.

# v2 API overview

> The LedgerSync v2 partner API: who it is for, its base URLs, and how an integration reads its clients' bank data.

> [!NOTE]
>
> **Starting a new integration? Use v3.** These pages cover the v2 API for integrations that are already built on it. New integrations should start with the [v3 API](https://docs.ledgersyncappv2.com/introduction.md).

The v2 API gives your software the bank data LedgerSync collects for your clients: their bank connections and accounts, transactions, bank statements and checks. It also manages your clients and employees, and hands out the Finicity or MX connect widget your clients use to link a bank. Requests and responses are JSON over HTTPS, apart from file uploads and downloads such as statement PDFs.

You authenticate by signing in with a LedgerSync login, and the API then acts as that login. For example, `GET /api/v2/client/list` returns all of your clients when you sign in with the login you created at sign-up, and only the clients assigned to an employee when you sign in as that employee.

## Base URLs

> [card] Sandbox
>
> `https://staging.ledgersyncappv2.com`
>
> A separate LedgerSync environment for building and testing. Create a login at [staging.ledgersyncappv2.com/sign-up](https://staging.ledgersyncappv2.com/sign-up).

> [card] Production
>
> `https://ledgersyncappv2.com`
>
> Your clients' real bank data. Create a login at [ledgersyncappv2.com/sign-up](https://ledgersyncappv2.com/sign-up).

Both environments serve the same paths, all under `/api/v2/`. They do not share logins or data: a login you create in the sandbox does not exist in production, so sign up in each. When you sign up, the email address you enter becomes your username. Try your integration in the sandbox first; [Testing](https://docs.ledgersyncappv2.com/v2/testing.md) covers what it offers.

> [!NOTE]
>
> The sandbox address in the old v2 docs, `104.196.54.242.sslip.io`, no longer works. Use `https://staging.ledgersyncappv2.com`.

## Sign in first

Every call outside `/api/v2/public/` needs a token. Get one by signing in:

```bash theme={null}
curl -X POST "https://staging.ledgersyncappv2.com/api/v2/public/authenticate" \
  -H "Content-Type: application/json" \
  -d '{ "username": "you@yourfirm.com", "password": "your-password" }'
```

The response's `authToken` starts with `Bearer`. Send that whole value in an `Auth-Token` header on every other call. It lasts 30 minutes, then you sign in again. [Authentication](https://docs.ledgersyncappv2.com/v2/authentication.md) has the details, the errors and logout.

## How an integration reads data

Reading a client's transactions takes three calls after sign-in, and each one hands you the values the next one needs. The snippets assume two variables:

```bash theme={null}
export LS_BASE="https://staging.ledgersyncappv2.com"
export LS_TOKEN="BearereyJhbGciOiJIUzUxMiJ9..."   # the authToken from sign-in
```

**1. List your clients**

```bash theme={null}
curl "$LS_BASE/api/v2/client/list" \
  -H "Auth-Token: $LS_TOKEN"
```

Each entry in `clients` has a `username`. That username is how every other endpoint names the client. When you sign in with the login you created at sign-up, the list also includes that login itself, under its own username.

**2. List the client's bank accounts**

```bash theme={null}
curl "$LS_BASE/api/v2/account/jane@example.com" \
  -H "Auth-Token: $LS_TOKEN"
```

The response lists the client's `banks`. Each bank carries its `source`, the data provider behind it, and its `accounts`, each with an `id`. Trimmed:

```json theme={null}
{
  "banks": [
    {
      "id": 276,
      "name": "Main Street Bank",
      "source": "FINICITY",
      "accounts": [{ "id": 654, "name": "Checking" }]
    },
    {
      "id": 1093,
      "name": "Harbor Credit Union",
      "source": "MX",
      "accounts": [{ "id": 8810, "name": "Savings" }]
    }
  ],
  "status": "OK"
}
```

Ids are numbered separately per source, so the same number can belong to a FINICITY account and to an MX account. Always keep an account's `id` together with its bank's `source`.

**3. List each account's transactions**

```bash theme={null}
curl "$LS_BASE/api/v2/transactions/list?username=jane@example.com&source=MX&accountId=8810&page=0" \
  -H "Auth-Token: $LS_TOKEN"
```

Send the bank's `source` and the account's `id` as `accountId`. Leave `source` out and the call reads FINICITY data, so an MX account comes back `200` with no transactions and no error. Results are newest first and paged: `page` starts at 0, and `rowsPerPage` is 10, 20 or 50 (default 50).

> [!TIP]
>
> The transaction list reads what LedgerSync has stored and never contacts the bank, so a connection that has broken still returns everything collected before it broke. Dates, paging and ids for each source are in [Transactions](https://docs.ledgersyncappv2.com/v2/transactions.md).

## Endpoint groups

Every endpoint, with its parameters and responses, is in the API reference pages of this tab. In short:

| Group | Endpoints | What they do |
| - | - | - |
| Authentication | `POST /api/v2/public/authenticate`, `/api/v2/public/authenticate-by-email`, `/api/v2/public/logout` | Sign in for a token, and sign out. |
| Clients | `/api/v2/client/...` | List, add, update, lock, unlock and delete clients, and change a client's password. |
| Accounts | `/api/v2/account/...` | List a client's banks and accounts, get a connect-widget link to add a bank or repair a connection, read an account summary or sub-accounts, and rename, refresh or delete a bank connection. |
| Transactions | `/api/v2/transactions/...` | List stored transactions, refresh a bank's transactions, and refresh historic transactions for chosen accounts. |
| Statements | `/api/v2/statements/...` | List statements and download their PDFs, refresh statements (answering the bank's MFA question when it asks one), convert a PDF statement to XLS or QBO, or extract its transactions as JSON. |
| Checks | `GET /api/v2/checks` | List checks with their images, payee, amount and check number. |
| Institutions | `GET /api/v2/institutions`, `GET /api/v2/institutions/provider-options` | Search one provider's list of banks, and find which providers cover a bank before you add it. |
| Employees | `/api/v2/employee/...` | Add, list, update, lock, unlock and delete your employees' logins, and change an employee's password. |
| Passwords and phone | `/api/v2/public/password/...`, `/api/v2/public/phone-verification/validate` | Send a password reset email by username or email, set a new password, and check a phone verification code. |
| Accounting AI | `POST /api/v2/accounting/{platform}/transactions/rules/ai/suggest-external` | Generate an AI rule suggestion for one transaction. |

## Where to go next

> [card] [Authentication](https://docs.ledgersyncappv2.com/v2/authentication.md)
>
> Sign in, send the token, and sign in again every 30 minutes.

> [card] [Transactions](https://docs.ledgersyncappv2.com/v2/transactions.md)
>
> The transaction list in full: parameters, dates and paging for each source.

> [card] [Transaction status](https://docs.ledgersyncappv2.com/v2/transaction-status.md)
>
> The status values each source returns on a transaction.

> [card] [Testing](https://docs.ledgersyncappv2.com/v2/testing.md)
>
> Build against the sandbox before you go live.

> [card] [v3 API](https://docs.ledgersyncappv2.com/introduction.md)
>
> Starting a new integration? Start here.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.