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

# Retrieve payment holds via API

In this tutorial, you learn how to retrieve payment holds via API. You can call two endpoints to retrieve holds:

- Retrieve multiple payment holds

- Retrieve a single payment hold by ID

### Before you begin

To retrieve payment holds via API, you need the following:

- A registered and fully onboarded developer account on the J.P. Morgan Payments Developer Portal

- Code to generate a bearer token. See the [quick start](/docs/quick-start) guide for instructions.

### Retrieve multiple payment holds

Use `GET /holds` endpoint to retrieve a list of payment holds based on filter criteria. Filter your results using query parameters. These are the most common examples:

 
**Retrieve multiple payment holds use case**

| Use case | Query parameter | Example | 
| --- | --- | --- | 
| Get all holds pending your review | substatus | /holds?substatus=PENDING_ACTION_CLIENT | 
| Get all holds pending JPMorganChase review | substatus | /holds?substatus=PENDING_ACTION_JPM | 
| Get all holds already decisioned | status | /holds?status=APPROVED,REJECTED | 

Sample response:

```json
{
  "items": [
    {
      "id": "1f8c3a2e-7b54-4d9a-8c3f-12ab34cd56ef",
      "status": "PENDING",
      "substatus": "PENDING_ACTION_JPM",
      "exceptionType": "BANK_RULE",
      "heldAt": "2026-02-01T14:15:22Z",
      "cutOffAt": "2026-02-06T14:15:22Z",
      "rules": [
        {
          "id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
          "name": "Client ABC Rule for Suspicious Beneficiary",
          "effectiveDate": "2019-08-24"
        }
      ],
      "payment": {
        "requestedExecutionDate": "2026-02-01",
        "paymentIdentifiers": {
          "endToEndId": "E2E3000113WEBXX"
        },
        "value": {
          "currency": "USD",
          "amount": "10.50"
        },
        "transferType": "DEBIT",
        "paymentType": "WIRE",
        "debtor": {
          "party": {
            "name": "Nicholas Tesla"
          },
          "account": {
            "accountNumber": "987654321",
            "accountCurrency": "USD"
          }
        },
        "remittanceInformation": {
          "unstructuredInformation": [
            {
              "text": "Music services INV#09900"
            }
          ]
        }
      }
    },
    {
      "id": "06bca14f-1fc0-4cd7-9e0b-8bb7e06334f7",
      "status": "PENDING",
      "substatus": "PENDING_ACTION_CLIENT",
      "exceptionType": "BANK_RULE",
      "heldAt": "2026-03-01T14:15:22Z",
      "cutOffAt": "2026-03-15T14:15:22Z",
      "rules": [
        {
          "id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
          "name": "Client ABC Rule for Suspicious Beneficiary",
          "effectiveDate": "2019-08-24"
        }
      ],
      "payment": {
        "requestedExecutionDate": "2026-03-10",
        "paymentIdentifiers": {
          "endToEndId": "E2E5908713WEBXX"
        },
        "value": {
          "currency": "USD",
          "amount": "250000"
        },
        "transferType": "DEBIT",
        "paymentType": "WIRE",
        "debtor": {
          "party": {
            "name": "Thomas Edison"
          },
          "account": {
            "accountNumber": "123456789",
            "accountCurrency": "USD"
          }
        },
        "remittanceInformation": {
          "unstructuredInformation": [
            {
              "text": "Cleaning INV#12300"
            }
          ]
        }
      }
    }
  ],
  "metadata": {
    "pagination": {
      "page": 1,
      "size": 25,
      "totalCount": 2,
      "totalPages": 1
    },
    "asOf": "2026-04-01T00:00+00:00"
  }
}
```

The response includes an array of payment hold objects and pagination metadata.

**Hold information**

Each item in the items array contains hold details such as status, substatus, heldAt and cutOffAt. If the hold has already been decisioned, the decision field contains information about how it was decisioned.

**Pagination**

The metadata.pagination object contains information about the current page of results:

 
**The metadata.pagination object contains information about the current page of results**

| Field | Description | 
| --- | --- | 
| page | Current page number | 
| size | Number of items per page | 
| totalCount | Total number of holds matching your query | 
| totalPages | Total number of pages available | 

**Error handling**

This request can fail for several reasons, such as invalid query parameters or authentication errors. See [API reference](/api/fraud-solutions/alerts-and-decisioning/overview) for details about field requirements and possible error responses.

## Retrieve a single payment hold by ID

Use `GET /holds/{id}` endpoint to retrieve the full details of a specific payment hold when you know its unique identifier.

Sample response:

```json
{
  "id": "06bca14f-1fc0-4cd7-9e0b-8bb7e06334f7",
  "status": "PENDING",
  "substatus": "PENDING_ACTION_CLIENT",
  "exceptionType": "BANK_RULE",
  "heldAt": "2026-02-01T14:15:22Z",
  "cutOffAt": "2026-02-06T14:15:22Z",
  "rules": [
    {
      "id": "59be9844-3a70-4fbc-8d58-9637c1b34b18",
      "name": "Client ABC Rule for Suspicious Beneficiary",
      "effectiveDate": "2019-08-24"
    }
  ],
  "payment": {
    "requestedExecutionDate": "2026-02-01",
    "paymentIdentifiers": {
      "endToEndId": "E2E3000113WEBXX"
    },
    "value": {
      "currency": "USD",
      "amount": "10.50"
    },
    "transferType": "DEBIT",
    "paymentType": "WIRE",
    "paymentTypeInformation": {
      "serviceLevelCode": "NURG",
      "localInstrumentCode": {
        "code": "WEB"
      }
    },
    "debtor": {
      "party": {
        "name": "Nicholas Tesla"
      },
      "account": {
        "accountNumber": "987654321",
        "accountCurrency": "USD"
      },
      "postalAddress": {
        "type": "HOME",
        "addressLines": [
          "10007 S. Lake Drive"
        ],
        "streetName": "10007 Lake Dr",
        "postalCode": "48035",
        "city": "Clinton Township",
        "countrySubDivision": "MI",
        "country": "US"
      }
    },
    "paymentPurpose": {
      "categoryPurpose": {
        "proprietary": "PURCHASE"
      }
    },
    "remittanceInformation": {
      "unstructuredInformation": [
        {
          "text": "Music services INV#09900"
        }
      ]
    }
  }
}
```

The response contains the complete payment hold object, including hold metadata and full payment details.

**Hold information**

The response includes hold details such as status, substatus, heldAt and cutOffAt. If the hold has already been decisioned, the decision field contains information about how it was decisioned.

**Payment details**

The payment object contains the full payment instruction, including debtor information, payment value and remittance information.

#### Error handling

This request can fail for several reasons, such as an invalid hold ID or authentication errors. See [API reference](/api/fraud-solutions/alerts-and-decisioning/overview) for details about field requirements and possible error responses.