---
title: "List the Books instances you can act on"
method: GET
path: "/books/instances"
tags: ["Books"]
---

# List the Books instances you can act on

`GET /books/instances`

## Request

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

Lists the Books instances, i.e. organizations' books (their general ledger: chart of accounts, journal entries, and reports), that this token can act on. Call this first, then pass an instance's `booksId` as the `booksId` argument of the other Books operations, such as the list ledgers endpoint (getBooksLedgers). A token can only act on its own organization's Books instance, so this lists at most that one instance; where `booksId` is optional, the token may omit it. Each instance has its `booksId`; the `organizationId`, `companyName`, and `callsign` of the organization it belongs to; and its `relationship` to the token's organization, which is `self`. Lists exactly the instances the other Books operations would let this token act on, given the scopes those operations need: the token's user must be an active member of the instance's organization with permission to manage Books, code transactions, and manage accounting integrations, and with access to all of its accounts, and the organization must have access to Books. An empty list means there is no instance this token can act on. Instances are sorted by `companyName`, ignoring case, and returned a page at a time: when the response has a `nextPageToken`, pass it as `pageToken` to get the next page.

## Query parameters

- `pageToken` string: token for pagination
- `limit` integer: The maximum number of instances to return per page, from 1 to 1000. Defaults to 100.

## Response `200`

- GetBooksAPIInstancesResponse: Response listing a page of the Books instances the token can act on.
  - `instances` BooksAPIInstance[], required: The Books instances on this page, sorted by company name.
    - `booksId` string, uuid, required: The Books instance's ID. Pass it as `booksId` to the other Books operations to act on this instance.
    - `callsign` string, required: The callsign, a short unique handle, of the organization the Books instance belongs to.
    - `companyName` string, required: The name of the organization the Books instance belongs to.
    - `organizationId` string, uuid, required: The ID of the organization the Books instance belongs to.
    - `relationship` 'self' | 'client', required: Whether the instance belongs to the token's own organization (`self`) or to one of its clients (`client`).
  - `nextPageToken` string, nullable: Pass as `pageToken` to fetch the next page, or null on the last page.

## Other responses

- `400`: Invalid `limit` or `pageToken`

## Changes

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

[Operation history](https://skmtc.dev/mercurytechnologies/apis/mercury-api/changes/books/instances/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)