---
title: "Query Sub-Account"
method: GET
path: "/merchant/open/institution/v1/accounts/query"
---

# Query Sub-Account

`GET /merchant/open/institution/v1/accounts/query`

Query sub-account details.

## Query parameters

- `request_id` string
- `account_id` string

## Headers

- `X-GatePay-Certificate-ClientId` string, required
- `X-GatePay-Timestamp` string, required
- `X-GatePay-Nonce` string, required
- `X-GatePay-Signature` string, required

## Response `200`

Success

- QuerySubAccountResponseWrapper
  - `status` string
  - `code` string
  - `errorMessage` string
  - `data` QuerySubAccountResponse
    - `request_id` string — Creation request ID.
    - `account_id` string — Sub-account ID.
    - `customer_id` string — Customer ID on the platform side.
    - `display_name` string — Display name.
    - `status` string — Account status: initial - INIT, processing - PENDING, created - ACTIVE, creation failed - FAIL.
    - `created` integer — Creation time (milliseconds).
    - `updated` integer — Last updated time (milliseconds).
    - `account_holder` AccountHolder
      - `entity_country` string, required — Entity's country ISO code. For the full list, refer to the official ISO online browsing platform or public ISO 3166-1 alpha-2 tables (e.g. https://www.iban.com/country-codes).
      - `entity_type` 'INDIVIDUAL' | 'BUSINESS', required — Entity type: individual - INDIVIDUAL, business - BUSINESS.
      - `entity_name` string, required — Entity name (person's full name / legal business name).
      - `entity_id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE' | 'BUSINESS_LICENSE' | 'CERTIFICATE_OF_INCORPORATION', required — ID document type. See Document Type Enumeration (PASSPORT, NATIONAL_ID, DRIVING_LICENSE for individual; BUSINESS_LICENSE, CERTIFICATE_OF_INCORPORATION for business).
      - `entity_id_number` string, required — ID document number.
      - `entity_id_expiry` EntityIdExpiry, required
        - `valid_from` integer, required — Effective date, in milliseconds.
        - `valid_to` integer — Expiry date, in milliseconds.
      - `dob` Dob
        - `year` integer, required — 4-digit year.
        - `month` integer, required — Month, 1–12.
        - `day` integer, required — Day of month, 1–31.
      - `business_registration` BusinessRegistration
        - `reg_number` string — Registration number.
        - `reg_country` string — Country of registration.
        - `established_at` integer — Date of establishment.
      - `address` Address, required
        - `line1` string, required — Address line 1.
        - `line2` string — Address line 2.
        - `line3` string — Address line 3.
        - `country` string, required — Country code.
        - `city` string — City.
        - `state` string — State / province.
        - `postal_code` string — Postal code.
      - `merchant_category` 'GENERAL_RETAIL' | 'SUPERMARKET_CONVENIENCE' | 'FASHION_AND_ACCESSORIES' | 'FOOD_AND_BEVERAGE' | 'DIGITAL_CONTENT_AND_SAAS' | 'GAMING_AND_ENTERTAINMENT' | 'TRAVEL_AND_TICKETING' | 'RIDE_HAILING_AND_TRANSPORT' | 'HOSPITALITY_AND_LEISURE' | 'EDUCATION' | 'HEALTHCARE_AND_WELLNESS' | 'FINANCIAL_SERVICES' | 'CRYPTO_AND_WEB3' | 'UTILITIES_AND_BILLS' | 'CHARITY_AND_NONPROFIT' | 'OTHER', required — Merchant category. See Merchant Category Enumeration.
      - `website` string — Business website.
      - `user_agreement` boolean, required — Whether the user has signed the agreement.
      - `ubo_list` Ubo[] — List of legal representative(s) and/or ultimate beneficial owner(s) (UBO). Required when entity_type is BUSINESS.
        - `country` string, required — Country ISO code.
        - `full_name` string, required — Full name of the individual.
        - `dob` Dob, required
          - `year` integer, required — 4-digit year.
          - `month` integer, required — Month, 1–12.
          - `day` integer, required — Day of month, 1–31.
        - `id_type` 'PASSPORT' | 'NATIONAL_ID' | 'DRIVING_LICENSE', required — Type of identification document for the individual.
        - `id_number` string, required — Identification document number.
        - `id_expiry` EntityIdExpiry, required
          - `valid_from` integer, required — Effective date, in milliseconds.
          - `valid_to` integer — Expiry date, in milliseconds.
        - `relationship` Relationship, required
          - `is_representative` boolean — Whether the individual is a legal representative.
          - `is_owner` boolean — Whether the individual is a beneficial owner.
          - `percent_ownership` string — Required when is_owner is true; represents the ownership percentage, for example 30.01.
    - `metadata` object — Additional key–value metadata.

---

[API](https://skmtc.net/gate/apis/gatepay-institutional-api.md) · [All operations](https://skmtc.net/gate/apis/gatepay-institutional-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gate/gatepay-institutional-api/versions/bb3314b74dc3/schema)