Jp Morgan Wallet

Get transactions based on filters

Overview

Get a list of transactions, filtering on parameters such as the end-to-end ID or the acceptance date and time.

You can get data about transactions with creationDateTime up to 180 days in the past.

Criteria

To get transactions 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 transactions by multiple parameters.

The following example criteria array gets transactions where the end-to-end ID is set to 1234567890.

Example criteria array

Json

{
    "criteria": [
        {
            "parameter": "endToEndIdentification",
            "clause": "eq",
            "value": "1234567890"
        }
    ]
}

Each object in the criteria array contains the following parameters:

parameter: Parameter by which to filter transactions. For example, set this to endToEndIdentification to search for transactions with a specific end-to-end ID.
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. Use for strings such as IDs.
- bt: "Between." Used to check if parameter is between two values. Use for amounts and dates.
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 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.

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

Get transactions 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 transactions with amounts less than $100, you can set value to: 0.01, 100.00
Get transactions with parameter equal to specific value: Set both values to the value for which you want to search. For example, to find transactions with amounts equal to $100, you can set value to: 100.00, 100.00
Get transactions 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 transactions 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 transactions as well as the clauses that you can use with them.

Criteria parameters
Parameter	Description	Clause	Examples
`acceptanceDateTime`	Date and time when Wallet accepted the request. Must be in UTC.	`bt`	Before a specific date: `2000-01-01T00:00:00Z, 2023-11-16T21:49:12Z` On a specific date: `2023-11-16T00:00:00Z, 2023-11-16T23:59:59Z` After a specific date: `2023-11-16T21:49:12Z, 3000-01-01T00:00:00Z`
`creationDateTime`	Date and time when the message was created. Must be in UTC.	`bt`	Before a specific date: `2000-01-01T00:00:00Z, 2023-11-16T21:49:12Z` On a specific date: `2023-11-16T00:00:00Z, 2023-11-16T23:59:59Z` After a specific date: `2023-11-16T21:49:12Z, 3000-01-01T00:00:00Z`
`creditorAccountIdentification`	Bank account number of the creditor account. Must be less than or equal to 34 characters.	`eq`	`1234567890`
`creditorAmount`	Amount that was credited to the creditor account. Must have less than or equal to four decimal places.	`bt`	Less than a specific amount: `0.00, 100.00` Equal to a specific amount: `90.45, 90.45` Greater than a specific amount: `100.00, 100000000000.00`
`creditorCurrency`	Currency of the funds credited to the creditor account. Must be an ISO 4217 three-character currency code.	`eq`	`GBP`
`debtorAccountIdentification`	Bank account number of the debtor account. Must be less than or equal to 34 characters.	`eq`	`1234567890`
`debtorAmount`	Amount that was debited from the debtor account. Must have less than or equal to four decimal places.	`bt`	Less than a specific amount: `0.00, 100.00` Equal to a specific amount: `90.45, 90.45` Greater than a specific amount: `100.00, 100000000000.00`
`debtorCurrency`	Currency of the funds debited from the debtor account. Must be an ISO 4217 three-character currency code.	`eq`	`USD`
`endToEndIdentification`	ID for tracing the request and its response across the API. Must be less than or equal to 16 characters.	`eq`	`E2E1234567890`
`paymentInformationIdentification`	ID for the payment batch. Must be less than or equal to 35 characters.	`eq`	`1cd83276-9172-49ce-873b-b24d3b85190f`
`requestedExecutionDate`	Date when the sender requested that Wallet execute the transaction. Must be in UTC and in `YYYY-MM-DD` format.	`bt`	Before a specific date: `2000-01-01, 2023-11-16` On a specific date: `2023-11-16, 2022-11-16` After a specific date: `2023-11-16, 3000-01-01`
`transactionStatus`	Status of the transaction. Must be one of the following values: `ACCEPTED` `CANCELED` `COMPLETED` `INITIATED` `PARTIALLY_COMPLETED` `PENDING` `REJECTED`	`eq`	`COMPLETED`
`transactionType`	Type of the transaction. Must be one of the following values: `PAYIN` `PAYINTO` `PAYINTOCOLLECTION` `PAYOUT` `PAYTO` `V2V`	`eq`	`PAYOUT`
`ultimateCreditorAccountIdentification`	ID of the ultimate creditor account. Must be less than or equal to 34 characters.	`eq`	`VTA-ID-1234567890`
`ultimateDebtorAccountIdentification`	ID of the ultimate debtor account. Must be less than or equal to 34 characters.	`eq`	`VTA-ID-1234567890`

Pagination

The API returns results in pages of transactions. Each API call returns one page. You set the number of transactions per page in pageSize (maximum 1,000).

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

The response includes a requestId field which identifies the query. If there are more transactions than can fit on the page, you can call the API again with the same filters to get subsequent pages of transactions by providing the requestId.

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

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 1,000, respectively.

Example request: Page 1

Json

{
    "criteria": [
        {
            "parameter": "creditorAccountIdentification",
            "clause": "eq",
            "value": "1234567890"
        }
    ]
}

The response includes the following:

Transactions where the creditor account ID equals 1234567890
requestIdentifier: abc123def456
totalRecordCount: 2,000

Note that the query found 2,000 matching transactions. Because the total number of transactions exceeds the page size of 1,000, only transactions 0-999 are returned.

To get the remaining 1,000 transactions, you can send the following request. criteria is omitted because we are using the same criteria as the previous request. startIndex is set to 1,000 because we already got transactions 0-999. requestIdentifier is set to the ID that we got from the response from the previous request.

Example request: Page 2

Json

{
    "groupHeader": {
        "reportPagination": {
            "startIndex": 1000,
            "pageSize": 1000
        },
        "requestIdentifier": "abc123def456"
    }
}

This request returns transactions 1,000-1,999.

Endpoints

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

Endpoints for "Get transactions based on filters" request
HTTP method	Request	v2.xx	v3.xx
`POST`	Get transactions based on filters	`/payments/advanced-search`	Not supported

Request

Header parameters

Include the following parameters in the header.

Header parameters for "Get transactions based on filters" API request
Parameter	Required / Optional	Description
`programId`	Required	Your Wallet program ID.

Body parameters

Include the following parameters in the request body.

Body parameters for "Get transactions based on filters" API request
Parameter	Required / Optional	Description
`criteria.clause`	Conditionally required	Clause to compare `parameter` and `value`. Required if `criteria` is present. Must be one of the following values: `bt`: "Between." Used to check if `parameter` is between two values. `eq`: "Equals." Used to check if `parameter` is equal to a value. For appropriate `clause` values to use for each `parameter`, see Criteria.
`criteria.parameter`	Conditionally required	Parameter of the transaction to use as a filter. Required if `criteria` is present. Must be one of the values listed in Criteria.
`criteria.value`	Conditionally required	Value to compare to the actual value of `parameter`. Required if `criteria` is present. For details, see Criteria.
`groupHeader.reportPagination.pageSize`	Conditionally required	Number of transactions to return per page. Must be 1-1,000. Default is 1,000. Optional in initial request; required in subsequent requests using the `requestIdentifier`. Required if `reportPagination` is present. For details, see Pagination.
`groupHeader.reportPagination.startIndex`	Conditionally required	Index of the first transaction to display. Must be 0-9,998. Default is 0. Optional in initial request; required in subsequent requests using the `requestIdentifier`. Required if `reportPagination` is present. For details, see Pagination.
`groupHeader.requestIdentifier`	Optional	If a previous request had more results than could fit in a single page, you can provide the `requestIdentifier` from the response to get more pages of results. If you provide this field, you can omit the `criteria` object, because Wallet stores the criteria from the previous request. For details, see Pagination.

Response

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

The maximum number of records per request is 10,000.

By default, the maximum number of records per page is 1,000.

Results are sorted by the date and time that transactions were created (transactionDetails.creationDateTime) in descending order.

Example

The following example request gets all outgoing transactions from a specific Virtual Transaction Account (VTA).

Example request: Get all outgoing transactions from a specific VTA

Json

{
    "groupHeader": {
        "reportPagination": {
            "startIndex": 0,
            "pageSize": 1000
        }
    },
    "criteria": [
        {
            "parameter": "ultimateDebtorAccountIdentification",
            "clause": "eq",
            "value": "VAID00002"
        }
    ]
}

The following is the response to the previous example request.

The number of transactions that matched the criteria is 2,302, but the page size is 1,000, so only the first 1,000 transactions are returned. For brevity, only the first transaction is included in this example.

To get the next 1,000 transactions, you could call the API again and provide the requestIdentifier from the response, set startIndex to 1000, and set pageSize to 1000.

Example response: Get all outgoing transactions from a specific VTA

Json

{
    "groupHeader": {
        "requestIdentifier": "1a2ead5b-bbd6-4009-94f3-5cbe6fdeea66",
        "totalRecordCount": 2302,
        "reportPagination": {
            "startIndex": 0,
            "pageSize": 1000
        },
        "executionDateTime": "2025-04-17T19:14:56"
    },
    "transactionDetails": [
        {
            "originalInstructionIdentification": "6f09a1eb-f648-41b8-ada8-3e0d8da22f29",
            "endToEndIdentification": "SK231117113919",
            "paymentInformationIdentification": "1cd83276-9172-49ce-873b-b24d3b85190f",
            "acceptanceDateTime": "2025-04-17T16:39:21Z",
            "equivalentAmount": {
                "amount": 5,
                "currency": "USD"
            },
            "requestedExecutionDate": "2025-04-17",
            "originalMessageNameIdentification": "PAYOUT",
            "creationDateTime": "2025-04-17T00:00",
            "transactionStatus": "REJECTED",
            "debtorAmount": {
                "amount": 5,
                "currency": "USD"
            },
            "creditorAmount": {
                "amount": 5,
                "currency": "USD"
            },
            "relatedParties": {
                "debtorAccountIdentification": "XXXXXXXXXX",
                "ultimateDebtorAccountIdentification": "VAID00002",
                "debtorAgentBranchNumber": "0802",
                "creditorAccountIdentification": "XXXXXXXXXX",
                "ultimateCreditorAccountIdentification": null,
                "creditorAgentBranchNumber": "0802"
            }
        }, 
        ... 999 remaining transactions in page from 2302 total transactions returned for provided criteria
    ]
}