> ## 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.

export const WhatComesNext = ({children, href}) => <div className="mt-4">
    <a href={href} className="btn-primary">
      {children} →
    </a>
  </div>;

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?

<CardGroup cols={3}>
  <Card title="API Overview" icon="https://mintcdn.com/pleo-61d4d38b/BSTL--ngUCT7NxE2/images/current/icons/api-overview.svg?fit=max&auto=format&n=BSTL--ngUCT7NxE2&q=85&s=212bb0c327550cf98f199582cb27eb45" href="/reference/company-balance/company-balance-api-overview" width="256" height="256" data-path="images/current/icons/api-overview.svg">
    <div className="text-sm mt-2">What the Company Balance API returns and how it's structured.</div>
  </Card>

  <Card title="API Scopes" icon="https://mintcdn.com/pleo-61d4d38b/earhx-WV21nRUBYy/images/current/icons/access-permissions.svg?fit=max&auto=format&n=earhx-WV21nRUBYy&q=85&s=5fdc4d93616eb532eb1b1e921e7775d7" href="/reference/company-balance/company-balance-api-scopes" width="256" height="256" data-path="images/current/icons/access-permissions.svg">
    <div className="text-sm mt-2">Required scope: `company-balance:read`.</div>
  </Card>

  <Card title="OAuth 2.0 Guide" icon="https://mintcdn.com/pleo-61d4d38b/earhx-WV21nRUBYy/images/current/icons/data-security.svg?fit=max&auto=format&n=earhx-WV21nRUBYy&q=85&s=da63c5719bf5fffaf0fe33c2d69c42ec" href="/docs/current/guides/oauth-workflow-guide" width="256" height="256" data-path="images/current/icons/data-security.svg">
    <div className="text-sm mt-2">End-to-end OAuth 2.0 workflow guide for Pleo integrations.</div>
  </Card>

  <Card title="OAuth 2.0 with Postman" icon="https://mintcdn.com/pleo-61d4d38b/earhx-WV21nRUBYy/images/current/icons/oauth-with-postman.svg?fit=max&auto=format&n=earhx-WV21nRUBYy&q=85&s=4007b8f53e4ed869b339e65c60681a28" href="/docs/current/guides/oauth-workflow-guide-postman" width="256" height="256" data-path="images/current/icons/oauth-with-postman.svg">
    <div className="text-sm mt-2">How to configure Postman to authenticate using OAuth 2.0 and call the Pleo API.</div>
  </Card>

  <Card title="Standalone API Key Guide" icon="https://mintcdn.com/pleo-61d4d38b/earhx-WV21nRUBYy/images/current/icons/permissions-access.svg?fit=max&auto=format&n=earhx-WV21nRUBYy&q=85&s=436e53e35075566c61df866d1fc39a68" href="/docs/current/guides/standalone-api-keys-workflow-guide" width="256" height="256" data-path="images/current/icons/permissions-access.svg">
    <div className="text-sm mt-2">End-to-end guide for authenticating with standalone API keys.</div>
  </Card>

  <Card title="Standalone API Keys with Postman" icon="https://mintcdn.com/pleo-61d4d38b/earhx-WV21nRUBYy/images/current/icons/oauth-with-postman.svg?fit=max&auto=format&n=earhx-WV21nRUBYy&q=85&s=4007b8f53e4ed869b339e65c60681a28" href="/docs/current/how-tos/api-keys/how-to-make-an-api-call-using-standalone-api-keys-postman" width="256" height="256" data-path="images/current/icons/oauth-with-postman.svg">
    <div className="text-sm mt-2">How to make API calls using standalone API keys in Postman.</div>
  </Card>
</CardGroup>

## 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. |

<WhatComesNext href="/reference/company-balance/get-the-balance-for-a-company">
  Get the balance for a company
</WhatComesNext>