Account Management APIs

Last updated on Apr 10, 2026 at 10:35 PM

---

Within the Common APIs, the Account Management section provides read access to account information relevant for transaction processing and operational visibility in ImPAI.

The Account Management API does not act as the system of record for accounts and does not perform account lifecycle operations. Instead, it exposes account data that is maintained in the underlying banking infrastructure and made available through ImPAI for reference and validation purposes.

Purpose: The Account Management API allows authorized clients to retrieve a structured list of accounts accessible within their context. This supports:

• Validation of account identifiers during transaction initiation,
• Operational visibility into available accounts,
• Consistent referencing of accounts across schemes and workflows.

info

At present, the section focuses on account discovery through the Account List endpoint. Future enhancements may extend this area with additional read-oriented capabilities where required.

---

1️⃣ List Accounts

The Account List API is to be used to retrieve detailed information about specific accounts, or request a list of available accounts.

Request Structure

❶  Query Parameters

The following request parameters can be used to filter for specific accounts:

Field	Type	Required	Description	Constraints
accountNumber	String	No	Filter accounts by exact account number.	–
currency	String	No	Filter accounts by currency code.	ISO 4217 three-letter currency codes
currentPage	String	No	Specify which page of results to retrieve when using pagination.	Decimal chars >= 1
customerId	String	No	Filter accounts by a specific customer identifier.	1-36 chars
entityCode	String	No	Filter accounts by entity code.	1-10 chars
iban	String	No	Filter accounts by International Bank Account Number (IBAN).	–
name	String	No	Filter accounts by account holder name.	1-140 chars
pageSize	String	No	Specify the maximum number of account records to return per page.	Decimal chars >= 1, <= 100, defaults 10
sortBy	String	No	Specify the field name to sort the results by.	Default: ACCOUNT_NUMBER Enum: ACCOUNT_NUMBER CREATED_AT CURRENCY CUSTOMER_ID IBAN NAME OPEN_DATE STATUS UPDATED_AT
sortOrder	String	No	Specify the sort direction for the sortBy field.	Default: asc Enum: asc desc
status	String	No	Filter accounts by their current status.	Enum: ACTIVE CLOSED INACTIVE PENDING SUSPENDED

Response Structure

🟢 Success — HTTP 200

HTTP 200 – OK responses for successfully processed messages include:

Group	Description
header	A group containing responseId, originalRequestId, responseTime
metaData	An object containing meta information about pagination and the actual request represented by pagination.currentPage, pagination.pageSize, pagination.totalPages, pagination.totalRecords, sort.sortBy, sort.sortOrder, filters, message, and timeStamp
results	An array of objects, each one containing detail information about 1 account: accountId, accountNumber, accountType, balance, createdAt, currency, customerId, entityCode, iban, isActive, lastTransactionDate, name, openDate, status, and updatedAt

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "metaData": {
    "pagination": {
      "currentPage": 1,
      "pageSize": 10,
      "totalPages": 5,
      "totalRecords": 47
    },
    "sort": {
      "sortBy": "accountNumber",
      "sortOrder": "asc"
    },
    "filters": { },
    "message": "Successfully retrieved 10 account(s)",
    "timeStamp": "2025-04-14T07:30:00Z"
  },
  "results": [
    {
      "accountId": "550e8400-e29b-41d4-a716-446655440000",
      "accountNumber": "ACC123456789",
      "accountType": "SAVINGS",
      "balance": 15000.5,
      "createdAt": "2023-01-15T09:00:00Z",
      "currency": "USD",
      "customerId": "CUST789012",
      "entityCode": "ENT001",
      "iban": "GB29NWBK60161331926819",
      "isActive": true,
      "lastTransactionDate": "2024-03-20T14:30:00Z",
      "name": "John Doe Savings Account",
      "openDate": "2023-01-15",
      "status": "ACTIVE",
      "updatedAt": "2024-03-20T14:30:00Z"
    }
  ]
}

🔴 Error — HTTP 400

Responses for HTTP 400 – Bad Request errors are returned if validation or logical checks fail and include:

Group	Description
header	Response metadata containing responseId, originalRequestId, responseTime
error	An object with a human-readable description in message
metaData	An object containing a general message about the error response (message and its timeStamp)

Example(s)

{
  "header": {
    "originalRequestId": "ReqId-419578",
    "responseId": "0a00f05f-c688-44db-b49a-af9aeed1a7ef",
    "responseTime": "2025-04-14T07:30:00Z"
  },
  "error": {
    "message": "Invalid query parameters provided"
  },
  "metaData": {
    "message": "Request failed due to an error",
    "timeStamp": "2025-04-14T07:30:00Z"
  }
}

🟡 Error — HTTP 500

Responses for HTTP 500 — Server Error errors are returned on unexpected server-side failures and contain:

Group	Description
errorCode	Application-level error identifier (e.g. 500_INTERNAL_ERROR)
message	Brief description such as "Time-out" or "Something went wrong"

Example(s)

{
  "errorCode": "500_INTERNAL_ERROR",
  "message": "Something went wrong"
}

⬇ Try this endpoint in the Live API Explorer

POST/common_services/common_account_list_psList available Accounts

---

Summary — Account Management

The Account Management section provides access to account information relevant for transaction processing and monitoring within the ImPAI platform.

Currently, this area exposes the Account List API, which allows authorized users to retrieve an overview of available accounts and their associated attributes.

The Account Management functionality:

• Enables discovery of accounts accessible to the calling user or client context,
• Returns structured account metadata required for transaction initiation or analysis,
• Supports consistent identification of accounts across schemes and workflows.

While the current scope focuses on listing accounts, the section is designed to grow alongside future enhancements such as detailed account views or configuration-related capabilities.