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

# Migrate to the Company Balance API

> How to migrate from the legacy Company Balance API to the current Company Balance API.

The legacy `GET /companies/balance` endpoint has been deprecated. This guide covers how to migrate to the new [Company Balance API](/reference/company-balance/company-balance-api-overview).

## New to the Company Balance API?

> **[API Overview](/reference/company-balance/company-balance-api-overview)**
>
> What the Company Balance API returns and how it's structured.

> **[API Scopes](/reference/company-balance/company-balance-api-scopes)**
>
> Required scope: `company-balance:read`.

> **[OAuth 2.0 Guide](/docs/current/guides/oauth-workflow-guide)**
>
> End-to-end OAuth 2.0 workflow guide for Pleo integrations.

> **[OAuth 2.0 with Postman](/docs/current/guides/oauth-workflow-guide-postman)**
>
> How to configure Postman to authenticate using OAuth 2.0 and call the Pleo API.

> **[Standalone API Key Guide](/docs/current/guides/standalone-api-keys-workflow-guide)**
>
> End-to-end guide for authenticating with standalone API keys.

> **[Standalone API Keys with Postman](/docs/current/how-tos/api-keys/how-to-make-an-api-call-using-standalone-api-keys-postman)**
>
> How to make API calls using standalone API keys in Postman.

## Getting Started

You'll need API credentials with the [`company-balance:read`](/reference/company-balance/company-balance-api-scopes) scope. Unlike the legacy endpoint, which returned the balance for the company identified by your bearer token, the new endpoint takes an explicit company ID.

## Key Differences

* The legacy endpoint (`GET /companies/balance`) returned a single, company-level wallet balance for the company identified by your bearer token. The new endpoint (`GET /v1/companies/{companyId}/balance`) takes an explicit `companyId` in the path and returns balances per account. Most companies have a single (primary) account, but the response is a list to support multi-account setups.
* Monetary values are now `{ currency, value }` objects instead of separate top-level fields, since currency can vary by account.
* The new endpoint also reports overdraft and pending-debit information for each account, which the legacy endpoint didn't expose.

## Field Mapping

The table below maps fields from the legacy `CompanyBalance` model to their equivalents on an entry in the new API's `data.accounts[]` list. For a company with a single account, use the entry where `isPrimary` is `true` for the closest legacy equivalent.

* `—` : field is not available on the legacy model
* `*` : data is the same but represented differently

| Legacy `CompanyBalance` field | New API equivalent (`accounts[].balance`) | Description |
| :- | :- | :- |
| currency | `available.currency` / `current.currency` **\*** | Now carried per `Money` field instead of once at the top level. |
| current | `current.value` **\*** | The account's current balance. |
| available | `available.value` **\*** | The account's available balance. |
| — | `overdraftLimit` | The maximum overdraft amount available on the account. |
| — | `usedOverdraft` | The amount of overdraft currently in use on the account. |
| — | `pendingDebits` | The total value of debits that have been authorised but not yet settled. |

[Get the balance for a company →](/reference/company-balance/get-the-balance-for-a-company)