List Institutions

POST/web/v1/system/institutions/query WEB

Required Gateway Headers

All API requests require gateway headers. See Required Headers for the complete list. In local/test environments, you must also include Cloudflare simulation headers (CF-Connecting-IP, Cf-Ray, cf-ipcountry).

Returns a paginated list of institutions with optional filtering.

Required Headers

Header	Example Value	Description
Content-Type	application/json	Request content type
Accept	application/json	Expected response type
X-Client-Hash		Client device fingerprint
Accept-Language	en, zh, zh-Hant, ja, vi	Response language (default: en)
Authorization	Bearer	JWT access token

Request Parameters

Path Parameters

Name	Type	Required	In	Description
workspaceId	string	Required	path	Workspace business ID

Request Body

InstitutionQueryRequest:

Name	Type	Required	In	Description
institutionBizId	string	Optional	body	Filter by institution business ID
institutionType	string | integer	Optional	body	Filter by institution type. Accepts either a string name (e.g., "PLATFORM", "TENANT") or the numeric code (e.g., 10010601).
institutionStatus	string	Optional	body	Filter by status: PENDING, REVIEWING, ACTIVE, REJECTED, SUSPENDED, CLOSED
institutionName	string	Optional	body	Filter by institution name (partial match)
page	integer	Optional	body	Page number (0-based, default: 0)
size	integer	Optional	body	Page size (1-100, default: 20)

Success Response

Success 200

{
  "code": "2000",
  "message": "SUCCESS",
  "data": {
    "institutions": [
      {
        "bizId": "inst_abc123",
        "institutionName": "Acme Corp",
        "institutionDescription": "Main institution",
        "institutionRemark": null,
        "institutionType": "TENANT",
        "institutionStatus": "ACTIVE",
        "extraConfig": null,
        "createdAt": "2026-03-21T00:00:00Z",
        "updatedAt": "2026-03-21T00:00:00Z"
      }
    ],
    "totalElements": 1,
    "totalPages": 1,
    "currentPage": 0,
    "pageSize": 20
  }
}

Error Responses

Code	Description
4000	Validation error (invalid page/size values)
4010	Unauthorized (invalid or missing JWT token)

Notes

• All filter fields are optional; omit them to retrieve all institutions.
• The response is paginated with default page size of 20.
• institutionType accepts both integer codes (e.g., 10010601) and string names (e.g., "PLATFORM"). Both forms refer to the same enum values.