# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com # 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. ```json { "criteria": [ { "parameter": "accountCreateDate", "clause": "eq", "value": "2026-03-02" } ] } ``` 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. **Criteria parameters** | Parameter | Description | Examples | | --- | --- | --- | | accountCreateDate | Date when the virtual account was created. Must be in the following format: YYYY-MM-DD | - "clause": "bt" - "value": "2026-01-01, 2026-03-02" | | clientAssignedVirtualAccountId | ID of the virtual account. | - "clause": "eq" - "value": 1234567890 | | maximumBalance | Maximum balance of the VTA. | - "clause": "bt" - "value": "1.00, 100.00" | | minimumBalance | Minimum balance of the VTA. | - "clause": "bt" - "value": "1.00, 100.00" | | parentVirtualAccountIdentification | ID of the virtual account's parent VSA. | - "clause": "eq" - "value": "1234567890" | | postingRestrictionType | The type of posting restriction that is applied to the VTA. Must be one of the following values: - DEBIT - CREDIT - ALL | - "clause": "in" - "value": "DEBIT, ALL" | | prn | Payment Routing Number (PRN) assigned to the VTA. | - "clause": "eq" - "value": "*" (get all VTAs with PRNs) | | virtualAccountState | State/status of the virtual account. Must be one of the following values: - PENDING_OPEN - OPEN - PENDING_CLOSE - CLOSED | - "clause": "in" - "value": "PENDING_OPEN, OPEN" | | virtualAccountType | The type of virtual account. Must be one of the following values: - SUMMARY (Virtual Summary Account) - TRANSACTION (Virtual Transaction Account) | - "clause": "eq" - "value": "TRANSACTION" | ## 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. ```json { "criteria": [ { "parameter": "maximumBalance", "clause": "bt", "value": "1.00, 1000.00" } ] } ``` 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. ```json { "groupHeader": { "reportPagination": { "startIndex": 100, "pageSize": 100 } }, "criteria": [ { "parameter": "maximumBalance", "clause": "bt", "value": "1.00, 1000.00" } ] } ``` 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](/api/treasury/jp-morgan-wallet/doc#/operations/accountSearch). **Endpoints for "Get virtual accounts based on filters" request** | HTTP method | Request | v2.xx | v3.xx | | --- | --- | --- | --- | | POST | Get virtual accounts based on filters | Not supported | /wallets/search | ## Request ### Header parameters Include the following parameters in the header. **Header parameters for "Get virtual accounts based on filters" endpoint** | Parameter | Required / Optional | Description | | --- | --- | --- | | programId | Required | Your Wallet program ID. | ### Body parameters Include the following parameters in the request body. **Body parameters for "Get virtual accounts based on filters" endpoint** | Parameter | Required / Optional | Description | | --- | --- | --- | | criteria.clause | Required | Clause to compare parameter and value. Must be one of the values listed in [Criteria](#criteria). | | criteria.parameter | Required | Parameter of the virtual account to use as a filter. Must be one of the values listed in [Criteria](#criteria). | | criteria.value | Required | Value to compare to the actual value of parameter. For details, see [Criteria](#criteria). | | groupHeader.reportPagination.pageSize | Conditionally required | Number of virtual accounts to return per page. Required if reportPagination is present. Must be 1-100. Default is 100. For details, see [Pagination](#pagination). | | groupHeader.reportPagination.startIndex | Conditionally required | Index of the first virtual account to display. Required if reportPagination is present. Must be 0-998. Default is 0. For details, see [Pagination](#pagination). | ## 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. ```json { "criteria": [ { "parameter": "virtualAccountState", "clause": "eq", "value": "CLOSED" } ] } ``` 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. ```json { "groupHeader": { "requestIdentifier": "ebd17f87-28c2-4ec6-9daf-ed5c799832d9", "totalRecordCount": 3, "reportPagination": { "startIndex": 0, "pageSize": 3 }, "executionDateTime": "2025-02-07T15:12:01" }, "virtualAccountDetails": [ { "virtualAccountIdentification": "N77064018288", "virtualAccountType": "EVTA", "parentVirtualAccountIdentification": "DZWirPz5SkOfgtAbDOgEVw", "virtualAccountState": "CLOSED", "accountOptions": { "paymentRoutingNumber": { "paymentRoutingNumber": "XXXXXXXXXX", "status": "ACTIVE", "country": "US", "routingInformation": [ { "type": "ABA", "value": "028000024" } ] }, "balanceLimits": { "minimumBalance": "-99999999999.99", "maximumBalance": "99999999999.99" } }, "accountCreateDate": "2023-10-28" }, { "virtualAccountIdentification": "VTA-N770640wtwlo2-7", "virtualAccountType": "EVTA", "parentVirtualAccountIdentification": "DZWirPz5SkOfgtAbDOgEVw", "virtualAccountState": "CLOSED", "accountOptions": { "paymentRoutingNumber": { "paymentRoutingNumber": "XXXXXXXXXX", "status": "ACTIVE", "country": "US", "routingInformation": [ { "type": "ABA", "value": "028000024" } ] }, "balanceLimits": { "minimumBalance": "-20.0", "maximumBalance": "20.0" } }, "accountCreateDate": "2023-08-03" }, { "virtualAccountIdentification": "VTA-N770640k4sfx7", "virtualAccountType": "EVTA", "parentVirtualAccountIdentification": "DZWirPz5SkOfgtAbDOgEVw", "virtualAccountState": "CLOSED", "accountOptions": { "paymentRoutingNumber": { "paymentRoutingNumber": "XXXXXXXXXX", "status": "ACTIVE", "country": "US", "routingInformation": [ { "type": "ABA", "value": "028000024" } ] }, "balanceLimits": { "minimumBalance": "-20.0", "maximumBalance": "20.0" } }, "accountCreateDate": "2023-11-10" } ] } ```