Balances

The Balances endpoint allows you to retrieve single or multiple currency account balances held with Alpha along with the associated metadata.

The balance is the amount of money available on a currency account. It is the difference between the sum of debit entries and the sum of credit entries entered into a currency account during a financial period.

See the Balances API reference section for technical implementation.

Return all balances

If no parameters are provided, all balances for the currency accounts associated with the connection will be returned. In the scenario where the connection has multiple entities, all currency accounts will be returned for all accounts.

See this diagram on the reporting API guide for explanation of the relationship between the different entities.

Return specified balances

Including query parameters in your request will constrain your search, but will be useful if you are looking to return a single or group of balances based on certain criteria eg specifying Currency to return all USD balances.

You may use any number of query parameters. Please note that using multiple parameters will make them all applicable. Querying parameters acts as an AND function, not OR.

📚 Any terms that you don’t understand below? Check out the glossary

Request Parameters

Name	Type	Use case
`EntityId`	string	Use this ID to only return currency accounts for a given entity
`AccountId`	string	If you only want to return the balance for a specific currency account, you can enter the ID of the currency account here
`Currency`	string	Return balances for a particular currency. Use the ISO 4217 format
`Iban`	string	Specify the IBAN to only return balances for currency accounts using that particular IBAN

Response

The response will include an array of balances

Name	Type	Description
`Amount`	string	The balance amount on the currency account
`EntityId`	string	This is the ID for entity that the currency account belongs to
`Currency`	string	The currency of the balance in the ISO 4217 format
`CreditOrDebit`	string	Indicates whether the balance is in credit or debit ["Credit", "Debit"]
`Type`	string	The type of the balance ["Available", "Cleared"]
`Iban`	string	The International Bank Account Number used to pay into the associated currency account
`AccountId`	string	The currency account ID associated with the balance
`AccountReference`	string	A user friendly description of the account
`DateTime`	string	The date and time of the balance. As the balance may change in the future, this field indicates when the current balance amount was accurate

Integration Examples

Check your balances for a given currency

Find out how much USD you have in your currency accounts, call the balance endpoint, passing USD as the Currency parameter.

curl -X 'GET' \
  'https://sandbox.api.alphagroup.com/api/v1/balances?Currency=USD' \
  -H 'accept: text/plain' \
  -H 'authorization: Bearer **BearerTokenGoesHere**'

The following response shows all the USD balances that were available on your connection.

{
  "Balances": [
    {
      "Amount": 0.5,
      "EntityId": "405e7c7c-4cd7-407a-8b70-204285691e17",
      "Currency": "USD",
      "CreditOrDebit": "Credit",
      "Type": "Wallet",
      "Iban": "GB34BARC20000087836066",
      "AccountId": "a8c9b73c-e127-452b-9d69-d5160258a62b",
      "AccountReference": "A0020154",
      "DateTime": "2024-03-11T17:58:07+00:00"
    },
    {
      "Amount": 1,
      "EntityId": "1fa51fab-a903-4be9-9eae-8356641b6fb1",
      "Currency": "USD",
      "CreditOrDebit": "Credit",
      "Type": "Wallet",
      "Iban": "GB34BARC20000087836066",
      "AccountId": "695769c3-ea5a-4bea-b762-779519f33bf7",
      "AccountReference": "A0020154",
      "DateTime": "2024-03-11T17:58:07+00:00"
    }
  ],
  "IsLastPage": true
}

Return a balance on a currency account

To get a balance for a specific currency account specify the AccountId. In this example, an AccountId from the above result is used.

curl -X 'GET' \
  'https://sandbox.api.alphagroup.com/api/v1/balances?AccountId=695769c3-ea5a-4bea-b762-779519f33bf7' \
  -H 'accept: text/plain' \
  -H 'authorization: Bearer **BearerTokenGoesHere**'

This response shows the requested balance and its associated metadata

{
  "Balances": [
    {
      "Amount": 1,
      "EntityId": "1fa51fab-a903-4be9-9eae-8356641b6fb1",
      "Currency": "USD",
      "CreditOrDebit": "Credit",
      "Type": "Wallet",
      "Iban": "GB34BARC20000087836066",
      "AccountId": "695769c3-ea5a-4bea-b762-779519f33bf7",
      "AccountReference": "A0020154",
      "DateTime": "2024-03-11T18:00:38+00:00"
    }
  ],
  "IsLastPage": true
}

Updated 2 months ago