> This page is for Enterprise. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://citi-demo.ferndocs.com/enterprise/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://citi-demo.ferndocs.com/enterprise/_mcp/server. # Balances ### Overview The Balances API gives you visibility into your Citi bank account balances based on a specific account identifier, either: * Intraday (during the day specific period) * End of day * Historical dates (up to last 180 days) It can also be set up to respond with balances of accounts you have with other banks. Please contact your Citi sales representative for more information on the multi-bank capability. The response can be delivered in both JSON and XML formats. --- ### What will this help me with? **Cash Positioning** — View your real-time consolidated financial position right from your application. **Transaction Management** — Up-to-date account balance information helps manage cashflow, bank transaction reconciliation and expenses. **Error Detection** — Real-time data makes it easier to identify overspending, low balances, unusual transactions, and more. --- ### How it works #### To retrieve a balance for an account #### Make a request You will make a request for a balance for one or more of your accounts. #### Get the balance Citi will return the current balance for the account. The balance returned for a given request will depend on several factors: * The time of day in the local market where the account is setup * The local currency; balances are returned in the local currency * The local market and branch operating hours, cutoff and processing period. > **Info** > > Each market and branch may have its own cutoff periods. To see a current list of market-specific rules, see Markets or contact your Citi representative. --- ### Availability > **Warning** > > The Balances API is available 24x5. It is not available on weekends when scheduled maintenance may cause the system to be unavailable. Additional availability is determined by local branch time zones and hours. #### Formats The Balances API operation follows a custom schema format. The response will follow ISO20022 v2 (camt.052.001.02). > **Info** > > To learn more about the ISO20022 v2 (camt.052.001.02), please see the [Society for Worldwide Interbank Financial Telecommunication (SWIFT) standards](https://www.swift.com/swift-resource/35366/download). #### Intraday vs. End of Day balances * If no transaction has occurred during a day, then the End of Day balance would be available * The intraday balance is available when **1 transaction** has occurred on the account. * To get Intraday balance during the day, users should invoke the API specifying `from_date` and `to_date` as Today's or Present date. #### Branch operating hours and balances Balance availability is determined by the branch operating hours. As an example branch hours in Hong Kong and the United Kingdom are not the same hours due to their respective time zones. #### Cut-off and processing periods * Each branch has a cut-off and processing period. Transactions occurring during this time will appear during the following available intraday or end of day balance. * Local branch hours determine when the cut-off and processing periods start. For most branches, the cut-off and processing periods start after the branch or local clearing has closed for the day. * Branch and API requestor in the same time zone * Accounts in more than one time zone * Each branch has a cut-off and processing period where the balance information will not be available for a couple of hours * Local branch hours determine when this cut-off and processing period will commence. As an example, most of these will occur after the branch or local clearing has closed * If the system calling the Balance data is in another time zone from the account location, then the system design must cater for the account location cut-off period and branch hours * When the cut-off period has been reached, no intraday balance would be available * However, the **end of day** balance would be available, but the request must be for the previous day #### Date range Balances can be pulled for the past 180 days only. #### Countries Available in any country where Citi operates. Please speak with your Citi Representative for additional details. --- ### Testing considerations | # | Name | Description | | - | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Opening balance | The opening balance of all accounts will be 10,000 USD. During this time, the balance will be calculated using the net credit or debit entries each day from the 10,000 starting point. At the end of 10 days, the account balance will be reset to 10,000 USD. | | 2 | End-of-day balance | Regardless of the intraday or the end of day status, the account balance at the end of any day will be reported as: 1. **CLBD**: closing booked 2. **CLAV**: closing available | | 3 | Response limitations | The camt.052 definition for this API will not return: 1. **ITAV**: interim available 2. **ITBD**: interim booked 3. **PRCD**: previously closed booked balance 4. **FWAV**: forward available balance | | 4 | Foreign exchange conversion | Foreign exchange (FX) conversion of account currency is not available in the test environment; balances will be returned in the account's local currency. | --- ### Security requirements Citi uses access tokens to authenticate and authorize API requests from your application. To receive an access token from Citi you will first send an API request to our OAuth endpoint using your API credentials: client ID and secret key. Please visit the [Authentication guide](/enterprises/api-docs/authentication/overview) for more details.