---
title: "List a source account's transactions"
method: GET
path: "/books/transactions"
tags: ["Books"]
---

# List a source account's transactions

`GET /books/transactions`

## Request

- Base URL: `https://api.mercury.com/api/v1`
- URL: `https://api.mercury.com/api/v1/books/transactions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/mercurytechnologies/apis/mercury-api/docs/books/transactions/get.ts> (a function with typed inputs; its response is checked against the schema)

Returns one page of a source account's transactions within a date range. Use it to find transactions to categorize. sourceAccountId, startDate, endDate, and reviewStatus are required, as in the web app's transaction list. Get sourceAccountId from `GET /books/source-accounts` (getBooksSourceAccounts). To see both review statuses, make one request for each. A transaction needs categorizing when its `categorizationMethod` is `uncategorized`. To categorize or recategorize transactions, use `POST /books/transactions/categorize` (categorizeBooksTransactions) with each transaction's `journalEntryId`. A positive `amount` posts on the source account's `debitCredit` side, and a negative one on the opposite side. For a Mercury bank account, positive is money in. For a Mercury credit card, positive is a charge. Pass enrich=true to add Mercury banking details, such as the note, counterparty, and attachments. Each response is one page, and Books decides the page size. To see every transaction in the range, pass `nextPageToken` back as pageToken with the same other parameters, and repeat until a response has no `nextPageToken`. To read one transaction by ID, use `GET /books/transaction/{transactionId}` (getBooksTransaction).

## Query parameters

- `sourceAccountId` string, base58 (max length 22), required: unique id for a source account
- `booksId` string, uuid: The Books instance to act on. Must be the token organization's own instance, which it defaults to.
- `startDate` string, date, required
- `endDate` string, date, required
- `reviewStatus` 'reviewed' | 'unreviewed', required
- `pageToken` string: The nextPageToken (or prevPageToken) of a previous response, to fetch that page. Send the same sourceAccountId, startDate, endDate, and reviewStatus as that request. Omit for the first page.
- `enrich` boolean: Whether to add Mercury banking details, such as the note, counterparty, and attachments, to each transaction. Defaults to false.

## Response `200`

- GetBooksAPITransactionsResponse: One page of a source account's transactions.
  - `nextPageToken` string, nullable: Present when more transactions match the request. Pass it back as `pageToken`, with the same other parameters, to fetch the next page, and keep doing so until a response has no `nextPageToken`; only then have you seen every transaction in the range.
  - `prevPageToken` string, nullable: Present when there is an earlier page. Pass it back as `pageToken`, with the same other parameters, to fetch the previous page.
  - `transactions` BooksAPITransaction[], required: The transactions on this page: at most one page, whose size Books decides, so not necessarily every transaction in the date range.
    - `amount` number, double, required: The signed amount, in dollars. A positive amount posts on the source account's `debitCredit` side, increasing its ledger balance; a negative amount posts on the opposite side. Positive is money in for a Mercury bank account and a charge for a Mercury credit card; other source accounts follow their `debitCredit` and the signs their transactions were imported with.
    - `attachments` BooksAPITransactionAttachment[], nullable: Files attached to the Mercury transaction, such as receipts. Only included with `enrich=true`.
      - `downloadUrl` string, required: A presigned URL for downloading the attachment, valid for 1 hour.
      - `fileName` string, required: The file name of the attachment.
      - `id` string, required: The unique identifier of the attachment.
    - `cardLastFourDigits` string, nullable: The last four digits of the card used for the transaction. Only included with `enrich=true`.
    - `categorizationLines` BooksAPITransactionCategorizationLine[], required: The line entries that categorize the transaction: every other line of its journal entry. Empty when the transaction has no journal entry.
      - `amount` number, double, required: The unsigned amount of the line, in dollars; `debitCredit` gives its direction.
      - `debitCredit` 'debit' | 'credit', required: Whether the amount is a debit or a credit to the ledger.
      - `ledgerId` string, base58 (max length 22), required: The identifier of the ledger (general ledger account) the line posts to, i.e. the category.
      - `ledgerName` string, required: The display name of the ledger the line posts to.
      - `lineEntryId` string, base58 (max length 22), required: The identifier of the categorization line entry.
    - `categorizationMethod` 'ai' | 'rules' | 'similarity' | 'transferBetweenAccounts' | 'uncategorized' | 'user', nullable: How the transaction got its current category: `uncategorized` when no categorizer matched it, `user` when a person categorized it, and otherwise the automatic categorizer. Omitted when the transaction has not been categorized.
    - `counterpartyName` string, nullable: The name of the transaction's counterparty (who the money went to or came from). Only included with `enrich=true`.
    - `customCategoryId` string, nullable: The identifier of the Mercury custom category assigned to the transaction. Only included with `enrich=true`.
    - `customCategoryName` string, nullable: The name of the Mercury custom category assigned to the transaction. Only included with `enrich=true`.
    - `datetime` string, yyyy-mm-ddThh:MM:ssZ, required: When the transaction happened, in UTC.
    - `description` string, size < 513, required: The transaction's description, as imported from its source.
    - `id` string, required: The unique identifier of the transaction.
    - `journalEntryId` string, base58 (max length 22), nullable: The identifier of the transaction's journal entry. Omitted when the transaction has no journal entry, because it is not posted or its posting was deleted.
    - `ledgerId` string, base58 (max length 22), nullable: The identifier of the source account's ledger, which the transaction's own line entry posts to.
    - `lineEntryId` string, base58 (max length 22), nullable: The identifier of the transaction's own line entry, on the source account's ledger. Omitted when the transaction has no journal entry.
    - `merchantType` string, nullable: The display name of the merchant type (Mercury category) automatically assigned to the transaction, such as `Software`. Only included with `enrich=true`.
    - `note` string, nullable: The note on the Mercury transaction. Only included with `enrich=true`.
    - `personal` boolean, required: Whether the transaction is a personal (non-business) transaction.
    - `postedStatus` 'notPosted' | 'posted' | 'deleted', required: Whether the transaction has been posted to the general ledger as a journal entry (`posted`), not yet (`notPosted`), or was posted and then deleted (`deleted`).
    - `reviewStatus` 'reviewed' | 'unreviewed', required: Whether the transaction's categorization has been reviewed.
    - `sourceAccountId` string, base58 (max length 22), required: The identifier of the source account the transaction belongs to.
    - `teamMemberId` string, nullable: The identifier of the team member associated with the transaction, such as the cardholder. Only included with `enrich=true`.
    - `teamMemberName` string, nullable: The full name of the team member associated with the transaction. Only included with `enrich=true`.
    - `transactionMethodKind` 'outgoingElectronicPayment' | 'outgoingCheckPayment' | 'endogenousOutgoingAchTransfer' | 'endogenousIncomingAchTransfer' | 'exogenousOutgoingAch' | 'exogenousIncomingAch' | 'incomingCredit' | 'outgoingCredit' | 'incomingDebit' | 'outgoingDebit' | 'internalTransfer' | 'incomingCheck' | 'outgoingInternationalWire' | 'incomingInternationalWire' | 'outgoingDomesticWire' | 'incomingDomesticWire' | 'wireFee' | 'conversionFee' | 'personalBankingSubscriptionFee' | 'billingEngineSubscriptionFee' | 'physicalCardUpgradeFee' | 'exogenousOutgoingCheck' | 'exogenousOutgoingWire' | 'treasuryTransfer' | 'investTransfer' | 'currencyCloudReturn' | 'internationalWirePartnerReturn' | 'internalCreditAccountPayment' | 'autoRoutingTransfer' | 'ventureDebtFunding' | 'ventureDebtRepayment' | 'creditCashbackRewardsDeposit' | 'externalCreditCashbackRewardsDeposit' | 'interestPayment' | 'outgoingProvisionalCredit' | 'incomingProvisionalCredit' | 'lineOfCreditFunding' | 'lineOfCreditRepayment' | 'lineOfCreditInterestRepayment' | 'atmFeeReimbursement' | 'atmFeeReimbursementReversal' | 'expenseReimbursement' | 'requestedPayment' | 'exogenousWireDrawdown' | 'incomingCreditAccountRepayment' | 'cardIntlTransactionFee' | 'cardIntlTransactionFeeRebate' | 'cardIntlTransactionFeeReversal' | 'cardIntlTransactionFeeRebateReversal' | 'externalCreditAccountPayment' | 'realtimePayment' | 'outgoingRealTimePayment' | 'balanceHold' | 'linkedMercuryAccountTransfer', nullable: The kind of Mercury transaction, such as a card payment or a wire. Only included with `enrich=true`.

## Other responses

- `400`: Invalid `enrich` or `pageToken` or `reviewStatus` or `endDate` or `startDate` or `booksId` or `sourceAccountId`

## Changes

- **2026-11-03** `95c77a617769`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/transactions/get.md)

---

[API](https://skmtc.dev/mercurytechnologies/apis/mercury-api.md) - [All operations](https://skmtc.dev/mercurytechnologies/apis/mercury-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mercurytechnologies/apis/mercury-api/revisions/95c77a617769?raw)