API response body

{
  "page": 1,
  "num_pages": 7,
  "balances": [
    {
      "account_id": "default",
      "account_type": "depository",
      "balance": 6324.13,
      "timestamp": "2021-10-08T10:41:25+00:00",
      "currency": "KES",
      "labels": []
    }
  ]
}

Summary

A "Balance" is a measure of capital associated with an account, belonging to a user's Institution, at a given point in time.
For a depository type account, balance signifies the amount held in a depository account.
For a loan type account, balance signifies the principal amount owed to a loan account.

Query/Response Behavior

If no time range is provided in the query, the endpoint defaults to returning a single, latest balance record, on a per account_number basis.

Fields

balances[].account_id

Multiple accounts can be associated with an institution. The Balances endpoint returns the entire collection of records, across all possible accounts. It is possible that a user has multiple accounts (e.g. a savings and a checking), in which case Pngme attempts to extract the distinct account_id of each account. In this case, a call to the Balances API might show two sets of records, each grouped by different account_id. _If the account_id value is not extractable, this field shows as "account_id": "default".

balances[].account_type

The type of account associated with the set of records. See the Account Types section.

balances[].balance

The amount of the balance.

For a depository type account, balance is the balance on the account at that point in time.

For a loan or revolving_loan type account, balance is typically the outstanding principal amount, or total amount owed, on a loan.

balances[].timestamp

The time at which the balance record event occurred (specifically, when the SMS was received at the mobile phone user's phone)

balances[].currency

A currency field, if available. Currency is not always extractable for a given balance record. If no currency field is provided, consider using the default currency or country currency provided from the /users/{user_uuid}/institutions endpoint.
If present, currency is one of the recognized currency codes, as detailed in the Currency Codes section.

balances[].labels[]

One or more labels associated with the given balance record. See the Labels section for a list of recognized labels, and their description.

Interpreting labels

Example:

{
  "page": 1,
  "num_pages": 7,
  "balances": [
    {
      "account_id": "default",
      "account_type": "loan",
      "records":
     {
      "balance": 1800,
      "timestamp": "2021-10-14T11:33:36+00:00",
      "account_id": "default",
      "account_type": "loan",
      "currency": "NGN",
      "labels": ["LoanApproved", "LoanDisbursed"]
    }
  ]
}

The above is a balance statement, showing a principal balance owed of 1800 NGN, from an account of type "loan". This transaction has been labeled with two labels: LoanApproved and LoanDisbursed. Those labels signify that at the time of this transaction, a loan approval and loan disbursement event took place. Given that a LoanApproval event coincided with this balance statement, it stands to reason that 1800NGN is the loan size at time of Approval.