Total balance

Total Balance

This endpoint retrieves total balances broken down by agent for a given ISO (Independent Sales Organization). When both isoId and agentId are provided, results are filtered to the balance associated with the specified agent under the given ISO. It is designed to support financial tracking and agent-level performance monitoring.

Endpoint

GET /api/Widget/Balances

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when you need a financial summary of balances segmented by agent under a specific ISO. It is useful for partner dashboards, reporting tools, and operations teams that need to monitor agent-level balance distribution. Providing only isoId returns all agents under that ISO; adding agentId narrows the result to a single agent.

Query Parameters

Parameter	Type	Required	Description
isoId	integer	No	Unique identifier for the Independent Sales Organization (ISO) managing the agents.
agentId	integer	No	Unique identifier for the specific agent whose balance details are being requested. When combined with `isoId`, results are filtered to that agent under the given ISO.

Response

200 OK

Field	Type	Description
balance	integer (int64)	Total balance associated with the ISO or agent, expressed as an integer value.
isoId	integer (int32)	Identifier of the ISO to which this balance record belongs.

[
  {
    "balance": 154200,
    "isoId": 1042
  },
  {
    "balance": 87650,
    "isoId": 1043
  }
]

Error Codes

Code	When it happens
400	Invalid parameter type supplied for `isoId` or `agentId` (e.g., non-integer value).
401	Token missing, expired, or invalid.
403	Insufficient permissions to access balance data for the specified ISO or agent.
404	No balance records found for the provided `isoId` or `agentId`.
500	Internal server error.

Common Mistakes

Passing string or non-integer values for isoId or agentId — both parameters must be integers (int32).
Omitting both isoId and agentId may return an unexpectedly large dataset or an empty result depending on your partner scope; always provide at least isoId for meaningful results.
Expecting a single object in the response — the endpoint always returns an array of isobalance objects even when only one record matches.

Related Endpoints

GET /api/Widget/Transactions — Retrieve transaction history for agents under a given ISO.
GET /api/Widget/Agents — List agents associated with a specific ISO.

Example

curl -X GET "https://api.banking.netevia.dev/api/Widget/Balances?isoId=1042&agentId=501" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json"