# JPMC-PDP Documentation from https://developer.payments.jpmorgan.com

# 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`.

```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.

```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.

```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](/api/treasury/jp-morgan-wallet/doc-2#/operations/transactionAdvancedSearch).

 
**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). | 
| 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). | 
| criteria.value | Conditionally required | Value to compare to the actual value of parameter. Required if criteria is present. For details, see [Criteria](#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](#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](#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](#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).

```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`.

```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
    ]
}
```