Skip to main content
GET
/
v1
/
balances
List balance records
curl --request GET \
  --url https://api.wellapp.ai/v1/balances \
  --header 'Authorization: <authorization>'
{
  "data": [
    {
      "type": "balance",
      "id": "balance1",
      "attributes": {
        "local_balance": {
          "opening_booked": "123.32",
          "opening_value": "124.42",
          "closing_booked": "123.32",
          "closing_value": "124.42",
          "currency": "USD"
        },
        "accounting_balance": {
          "opening_booked": "123.32",
          "opening_value": "124.42",
          "closing_booked": "123.32",
          "closing_value": "124.42",
          "currency": "EUR"
        },
        "foreign_exchange": [
          {
            "currency_rate": "1.2546",
            "currency_pair": "EURUSD",
            "currency_rate_source": "European Central Bank",
            "currency_rate_at": "2025-06-01T14:30:00Z"
          }
        ],
        "balance_at_from": "2025-06-01T10:00:00Z",
        "balance_at_to": "2025-06-03T10:00:00Z"
      },
      "relationships": {
        "transactions": {
          "data": [
            {
              "type": "transaction",
              "id": "uuid1"
            }
          ]
        },
        "account": {
          "data": {
            "type": "payment_mean",
            "id": "uuid2"
          }
        },
        "workspaces": {
          "data": [
            {
              "type": "workspace",
              "id": "workspace_tenant"
            }
          ]
        }
      },
      "included": {
        "transaction": [
          {
            "type": "transaction",
            "id": "uuid1",
            "attributes": {
              "scheme": "sepa",
              "external_ids": {
                "transaction_id": "TXN_SEPA_20250601_001",
                "payment_request_id": "PAY_REQ_001",
                "end_to_end_id": "E2E_20250601_ACME_001"
              },
              "requested_execution_date": "2025-06-01",
              "executed_at": "2025-06-01T10:30:00Z",
              "booking_date": "2025-06-01",
              "value_date": "2025-06-01",
              "instructed_amount": {
                "currency": "EUR",
                "amount": 50
              },
              "settlement_amount": {
                "currency": "USD",
                "amount": 54.25
              },
              "foreign_exchange": {
                "currency_rate": "1.0850",
                "currency_pair": "EURUSD",
                "currency_rate_source": "European Central Bank",
                "currency_rate_at": "2025-06-01T10:00:00Z"
              },
              "transaction_type": "transfer",
              "status": "completed",
              "category_purpose": "CBFF",
              "purpose_code": "SALA",
              "remittance_information": {
                "unstructured": "Balance related transaction",
                "structured_reference": "RF18539007547034",
                "reference_type": "SCOR"
              },
              "fees": [
                {
                  "type": "transfer_fee",
                  "amount": 1.5,
                  "currency": "EUR"
                }
              ],
              "created_at": "2025-06-01T10:30:00Z",
              "updated_at": "2025-06-01T10:30:00Z"
            }
          }
        ],
        "account": [
          {
            "type": "payment_means",
            "id": "uuid2",
            "attributes": {
              "type": "account_details",
              "scheme": "ACH",
              "status": "active",
              "account_details": {
                "account_number": "1234567890",
                "routing_number": "021000021",
                "account_type": "checking",
                "currency": "USD"
              },
              "bank_details": {
                "bank_name": "JPMorgan Chase Bank, N.A.",
                "bank_code": "CHASUS33",
                "branch_name": "New York Main Branch",
                "branch_code": "NY001"
              },
              "compliance": {
                "kyc_status": "verified",
                "aml_status": "cleared"
              },
              "nickname": "Main Operating Account",
              "description": "Primary USD account for operations",
              "tags": [
                "usd",
                "operating",
                "primary"
              ],
              "created_at": "2025-06-01T10:00:00Z",
              "updated_at": "2025-06-01T10:00:00Z"
            }
          }
        ],
        "workspaces": [
          {
            "type": "workspace",
            "id": "workspace_tenant",
            "attributes": {
              "name": "Main Workspace",
              "description": "Primary workspace for financial operations",
              "created_at": "2025-06-01T08:00:00Z",
              "updated_at": "2025-06-01T12:00:00Z",
              "avatar_color": "#4A90E2",
              "external_workspace_id": "workspace-001",
              "auto_extract_enabled": true
            }
          }
        ]
      },
      "meta": {
        "total": 25,
        "page": 1,
        "per_page": 20,
        "total_pages": 2
      }
    }
  ]
}

Headers

​
Authorization
string
required

Bearer token for authentication

Query Parameters

​
include
enum<string>

Include detailed relationship data in the response. Comma-separated values supported.

Available options:
transactions,
account,
workspaces
​
filter[balance_at_from][from]
string<date-time>

Filter balances with balance_at_from on or after this date/time

​
filter[balance_at_from][to]
string<date-time>

Filter balances with balance_at_from on or before this date/time

​
filter[balance_at_to][from]
string<date-time>

Filter balances with balance_at_to on or after this date/time

​
filter[balance_at_to][to]
string<date-time>

Filter balances with balance_at_to on or before this date/time

​
filter[created_at][from]
string<date-time>

Filter balances created from this date/time

​
filter[created_at][to]
string<date-time>

Filter balances created up to this date/time

​
filter[updated_at][from]
string<date-time>

Filter balances updated from this date/time

​
filter[updated_at][to]
string<date-time>

Filter balances updated up to this date/time

​
filter[account_id]
string<uuid>

Filter balances by account ID (payment mean)

​
filter[workspace_id]
string<uuid>

Filter balances by workspace ID

​
filter[external_workspace_id]
string

Filter balances by external workspace ID

​
sort
enum<string>

Sort balances by field. Use - prefix for descending order.

Available options:
balance_at_from,
-balance_at_from,
balance_at_to,
-balance_at_to,
created_at,
-created_at,
updated_at,
-updated_at
​
page
integer
default:1

Page number for pagination

Required range: x >= 1
​
per_page
integer
default:20

Number of balances per page

Required range: 1 <= x <= 100

Response

Balance records retrieved successfully

​
data
object[]
​
meta
object