Get virtual accounts based on filters

Overview

Get a list of virtual accounts based on filters such as the parent ID or the minimum/maximum balance.

Note: You cannot query standard virtual accounts such as the Top-Level Virtual Summary Account (VSA) or the Default (Reconciliation) Virtual Transaction Account (VTA).

Criteria

To get virtual accounts that match certain filters, you set criteria in the request body. criteria is an array of objects, where each object represents a filter.

Because criteria is an array, you can add multiple objects to filter virtual accounts by multiple parameters.

The following example criteria array gets accounts where the account creation date is March 2, 2026.

Each object in the criteria array contains the following parameters:

• parameter: Parameter by which to filter virtual accounts. For example, set this to accountCreateDate to search for virtual accounts with a specific creation date.
• clause: How to compare parameter and value. Must be one of the following:
  • eq: "Equals." Used to check if parameter is equal to a value.
  • bt: "Between." Used to check if parameter is between two values. Use for amounts and dates.
  • in: "In." Used to check if parameter is equal to any of a list of values.
• value: Value to compare to the actual value of parameter. Note the following requirements:
  • If clause is set to eq, this field must only contain a single value (no commas). For example: 1234567890
  • If clause is set to bt, this field must contain two values separated by a comma. For example: 1.00, 100.00
  • If clause is set to in, this field must contain 1-10 comma-separated values. For example: PENDING_CLOSE, CLOSED
  • If you provide a date in this field, it must be in UTC.
  • If you provide an amount of funds in this field, it must have four decimal places or fewer.
  • You can set this parameter to * to mean "any value." For example, to search for all VTAs that have PRNs, you can specify the following:
    • "parameter": "prn"
    • "clause": "eq"
    • "value": "*"

When using the bt clause to filter parameters that are between two values, you can use the following tricks:

• Get virtual accounts with parameter less than specific value: Set the first value to a very low value and the second value to the maximum value for which you want to search. For example, to find virtual accounts with minimum balances less than $100, you can set value to: 0.01, 100.00
• Get virtual accounts with parameter equal to specific value: Set both values to the value for which you want to search. For example, to find virtual accounts with minimum balances equal to $100, you can set value to: 100.00, 100.00 (Alternatively, you can set clause to eq and value to the value.)
• Get virtual accounts with parameter greater than specific value: Set the first value to the minimum value for which you want to search, and the second value to a very high value. For example, to find virtual accounts with amounts greater than $100, you can set value to: 100.00, 1000000000.00

The following table lists the parameters by which you can filter virtual accounts.

Pagination

The API returns results in pages of virtual accounts. Each API call returns one page. You set the number of virtual accounts per page in pageSize (maximum 100).

The API returns virtual accounts starting with the startIndex that you set, returning virtual accounts chronologically in descending order by creation date until it hits the pageSize or runs out of virtual accounts. The maximum number of virtual accounts that the API can return is 10,000.

If there are more virtual accounts than can fit on the page, you can call the API again with the same filters and set startIndex to an account on the next page.

By default, if you omit startIndex, it is set to 0, and if you omit pageSize, it is set to 100.

In the first API call with given filters, you can omit startIndex and pageSize. However, in subsequent calls of the same query, you must provide both of these values.

For example, let's say you send the following query. Because startIndex and pageSize are omitted, they are set to 0 and 100, respectively.

The response includes the following:

• Virtual accounts where the maximum balance is between 1.00 and 1,000.00
• requestIdentifier: abc123def456
• totalRecordCount: 200

Note that the query found 200 matching virtual accounts. Because the total number of virtual accounts exceeds the page size of 100, only virtual accounts 0-99 are returned.

To get the remaining 100 virtual accounts, you can send the following request. criteria is the same as it was in the first request. startIndex is set to 100 because we already got virtual accounts 0-99.

This request returns virtual accounts 100-199.

Endpoints

Send an API request to one of the following endpoints to execute a request to get virtual accounts based on filters. For the specification, see the API reference.

Request

Header parameters

Include the following parameters in the header.

Body parameters

Include the following parameters in the request body.

Response

If the request is successful, the API returns a response with a list of virtual accounts matching your request criteria.

The maximum number of virtual accounts per request is 10,000.

By default, the maximum number of virtual accounts per page is 100.

Results are sorted by the date and time that virtual accounts were created (virtualAccountDetails.accountCreateDate) in descending order.

Example

The following example request gets all closed virtual accounts.

The following is the response to the previous example request.

totalRecordCount is set to 3, meaning the query returned 3 virtual accounts.

The request did not set pageSize, so it defaulted to 100. Because the number of virtual accounts returned is 3, all virtual accounts are able to fit on a single page, and pageSize was reduced to 3.