Balance Information

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/api-evangelist/citi/main/json-schema/citi-balance-information-schema.json",
  "title": "Balance Information",
  "description": "Response containing balance information returned to the TPP for one or more accounts.",
  "x-generated": "2026-10-12",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/citi-bankdatasharing-api-openapi.yml#/components/schemas/Balance-Information",
  "type": "object",
  "properties": {
    "consent_id": {
      "$ref": "#/$defs/Consent-Id"
    },
    "balances": {
      "type": "array",
      "title": "balances",
      "description": "Balance Details.",
      "items": {
        "$ref": "#/$defs/Account"
      }
    }
  },
  "$defs": {
    "Account": {
      "title": "Balance information per account",
      "description": "Account context and associated balance records within the balances response.",
      "type": "object",
      "required": [
        "account_ref"
      ],
      "properties": {
        "account_ref": {
          "$ref": "#/$defs/Account-Ref"
        },
        "account_number": {
          "$ref": "#/$defs/Account-Number"
        },
        "currency_code": {
          "$ref": "#/$defs/Currency-Code"
        },
        "account_name": {
          "$ref": "#/$defs/Account-Name"
        },
        "account_type": {
          "$ref": "#/$defs/Account-Type"
        },
        "branch_code": {
          "$ref": "#/$defs/Branch-Code"
        },
        "legal_entity": {
          "$ref": "#/$defs/Legal-Entity"
        },
        "branch_name": {
          "$ref": "#/$defs/Branch-Name"
        },
        "balance": {
          "type": "array",
          "title": "transactions details",
          "description": "Transactions Details.",
          "items": {
            "$ref": "#/$defs/Balance"
          }
        }
      }
    },
    "Account-Name": {
      "type": "string",
      "description": "Name or title assigned to the account. <br>- For GET Account, this parameter is optional. <br>- For GET Balance, this parameter is optional. <br>- For GET Transaction, this parameter is not required.",
      "title": "Account Name"
    },
    "Account-Number": {
      "type": "string",
      "minimum": 1,
      "maximum": 35,
      "description": "Account number of Citi's corporate client account. <br>- For GET Account, this parameter is required. <br>- For GET Balance, this parameter is required. <br>- For GET Transaction, this parameter is optional.",
      "title": "Account Number."
    },
    "Account-Ref": {
      "type": "string",
      "description": "**This parameter is required for GET Transactions and optional for GET Accounts and GET Balances.** Unique reference assigned to an account; when omitted (where optional), data is returned for all accounts linked to the client_id.",
      "title": "Account Identifier"
    },
    "Account-Type": {
      "type": "string",
      "minimum": 1,
      "maximum": 242,
      "description": "Classification of the financial account. <br>- For GET Account, this parameter is optional. <br>- For GET Balance, this parameter is optional. <br>- For GET Transaction, this parameter is not required.",
      "title": "Account Type"
    },
    "Balance": {
      "title": "Balance Details per account",
      "description": "Balance metrics for a specific account as returned by the balances endpoint.",
      "type": "object",
      "required": [
        "opening_available_balance",
        "opening_ledger_balance",
        "total_credit_amount",
        "total_debit_amount",
        "net_amount"
      ],
      "properties": {
        "equivalent_currency_code": {
          "$ref": "#/$defs/Currency-Code"
        },
        "opening_available_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "SThis is the amount of money in your account at the start of the business day that is immediately available for use. It includes all settled transactions from previous days and excludes any funds that are on hold or pending settlement.",
          "title": "Opening available balance"
        },
        "closing_available_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the amount of money in your account at the end of the business day (EOD) that is available for use. It represents the opening available balance plus all settled credits and minus all settled debits from that day.",
          "title": "Closing available balance"
        },
        "intraday_available_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the available balance of your account reflecting transactions that have occurred during the current business day but before the official end-of-day processing.",
          "title": "Intraday Available Balance"
        },
        "opening_ledger_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the book balance of your account at the start of the business day. It includes all transactions that have been formally posted to your account but may include items (like recently deposited checks) that have not yet cleared and are not part of your available balance.",
          "title": "Opening ledger balance"
        },
        "closing_ledger_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the book balance of your account at the end of the business day. It is calculated as the opening ledger balance adjusted for all credit and debit transactions posted during that day, regardless of their settlement status.",
          "title": "Closing ledger balance"
        },
        "intraday_ledger_balance": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the ledger balance of your account reflecting transactions that have been posted during the current business day but before the official end-of-day processing.",
          "title": "Intraday Ledger Balance"
        },
        "total_credit_amount": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This represents the sum of all incoming funds (credits) posted to your account during the business day.",
          "title": "Total credit amount"
        },
        "total_debit_amount": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This represents the sum of all outgoing funds (debits) posted from your account during the business day.",
          "title": "Total debit amount"
        },
        "net_amount": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is the net change in your account's balance for the day, calculated as Total Credit Amount minus Total Debit Amount.",
          "title": "Net amount"
        },
        "opening_available_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your opening available balance converted into a different currency of your choice. The conversion is performed using the provided fx_rate.",
          "title": "Opening Available Balance in Equivalent Currency"
        },
        "closing_available_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your closing available balance converted into a different currency of your choice (e.g., viewing your INR account balance in USD). The conversion is performed using the provided fx_rate.",
          "title": "Closing Available Balance in Equivalent Currency"
        },
        "intraday_available_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your intraday available balance converted into a different currency of your choice.",
          "title": "Intraday Available Balance in Equivalent Currency"
        },
        "opening_ledger_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your opening ledger balance converted into a different currency of your choice. The conversion is performed using the provided fx_rate.",
          "title": "Opening Ledger Balance in Equivalent Currency"
        },
        "closing_ledger_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your closing ledger balance converted into a different currency of your choice. The conversion is performed using the provided fx_rate.",
          "title": "Closing Ledger Balance in Equivalent Currency"
        },
        "intraday_ledger_balance_eqv_ccy": {
          "pattern": "^-?\\d{1,18}$|^-?\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This is your intraday ledger balance converted into a different currency of your choice.",
          "title": "Intraday Ledger Balance in Equivalent Currency"
        },
        "total_credit_amount_eqv_ccy": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This represents the sum of all incoming funds (credits) posted to your account during the business day in equivalent currency.",
          "title": "Total credit amount"
        },
        "total_debit_amount_eqv_ccy": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This represents the sum of all outgoing funds (debits) posted from your account during the business day in equivalent currency.",
          "title": "Total debit amount"
        },
        "statement_date": {
          "type": "string",
          "description": "This is the specific date to which the balance information applies.",
          "title": "Statement date",
          "format": "date-time"
        },
        "eod_date": {
          "type": "string",
          "description": "This field indicates the date of the last business day that has been fully processed and closed for the account's specific region. Due to global time zones, this may be the previous calendar day (e.g., an account in Japan will have an EOD date of the 18th while it is still the 18th in the US).",
          "title": "End of the day date",
          "format": "date-time"
        },
        "fx_rate": {
          "type": "number",
          "description": "This is the foreign exchange rate used to convert the account's native currency balance into the equivalent currency (_eqv_ccy) amounts.",
          "title": "FOREX Rate"
        },
        "effective_rate": {
          "type": "number",
          "description": "This represents the final, all-in exchange rate applied to the currency conversion, which may include any applicable spreads or transaction costs.",
          "title": "Effective Rate"
        },
        "intraday_last_update_date_time": {
          "type": "string",
          "description": "This timestamp indicates the exact date and time (in GMT) when the intraday balance information was last refreshed.",
          "title": "Intraday Last Update Date Time",
          "format": "date-time"
        },
        "last_entry_date": {
          "type": "string",
          "description": "This is the date on which the most recent transaction was formally posted to your account's ledger.",
          "title": "Last Entry Date",
          "format": "date-time"
        },
        "overdraft_details": {
          "$ref": "#/$defs/Overdraft-Details"
        }
      }
    },
    "Branch-Code": {
      "type": "string",
      "description": "Unique code identifying the servicing branch location. <br>- For GET Account, this parameter is optional. <br>- For GET Balance, this parameter is optional. <br>- For GET Transaction, this parameter is not required.",
      "title": "Branch Code"
    },
    "Branch-Name": {
      "type": "string",
      "description": "Name of the branch or local bank location servicing the account. <br>* For GET Account, this parameter is optional. <br>- For GET Balance, this parameter is optional. <br>- For GET Transaction, this parameter is not required.",
      "title": "Branch Name"
    },
    "Consent-Id": {
      "type": "string",
      "description": "Unique identifier of the account information consent used to authorize TPP data access.",
      "title": "Consent Identifier"
    },
    "Currency-Code": {
      "type": "string",
      "pattern": "^[A-Z]{3}$",
      "description": "Three-letter currency code defined by ISO 4217. <br>- For GET Account, this parameter is required. <br>- For GET Balance, this parameter is required. <br>- For GET Transaction, this parameter is not required.",
      "title": "Currency Code"
    },
    "Legal-Entity": {
      "type": "string",
      "description": "Legal entity name associated with the account (individual, corporate, or institution). <br>- For GET Account, this parameter is optional. <br>- For GET Balance, this parameter is optional. <br>- For GET Transaction, this parameter is not required.",
      "title": "Legal Entity"
    },
    "Overdraft-Details": {
      "title": "Overdraft Details",
      "type": "object",
      "description": "Overdraft-related values associated with the reported account balance.",
      "properties": {
        "overdraft_amount": {
          "pattern": "^\\d{1,18}$|^\\d{1,18}\\.\\d{1,5}$",
          "type": "number",
          "description": "This field shows the portion of your balance that is currently utilizing an approved overdraft limit. If your account is not in overdraft, this will typically be zero.",
          "title": "Overdraft Amount"
        }
      }
    }
  }
}