> ## Documentation Index > Fetch the complete documentation index at: https://docs2.finverse.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve Institutions list > Retrieve list of all Institutions. **Authorization**: `customer_token` or `link_token` ## Optional parameters You can use the following optional URL parameters to filter the Institutions list returned by Finverse. Example: `GET /institutions?products_supported=ACCOUNT_NUMBERS` # Response fields Full `institutions` array, containing a list of institutions with institution-level metadata. ### login_actions (array) (Informational) Details on dynamic login actions that may be required by the institution (e.g. 2FA). The Finverse Link UI will dynamically display any login actions. There are two types of login actions: \* Actions which require user-input inside the linking flow, e.g. 2FA steps requiring a code-input like SMS OTP or token-based OTP. These are labeled as `type` = `ACTION`. \* Actions which require the user to take action outside the linking flow, e.g. 2FA steps like push notification approval (in the user's bank app). In these cases the action flow provides an informational message to the user to complete the action step. These are labeled as `type` = `INFO`. ### buttons (array) For a given `login_action`, describes the user-facing buttons to display to enable the user to interact with the requested action. Only used for `type` = `ACTION`. ### fields (array) For a given `login_action`, describes the fields which require user-input to enable the user to interact with the requested action. Only used for `type` = `ACTION`. ### options (array) For a `field` with `type`\= `SELECT`, lists the possible options, from which user needs to select one value. ### messages (array) For a given `login_action`, describes the user-facing message(s) to inform the user about what action to take. ### login_details (object) Additional details on login requirements for each institution. ### login_methods (array) Additional details on login methods, containing `login_fields` for each institution. ### login_fields (array) For a given `login_method`, describes the login fields required to authenticate with the institution. These represent the minimum login fields required for all users. Additional fields may be required for some users (those will be dynamically displayed in Finverse Link). ### payment_info (object) Additional details on payment methods supported. ## OpenAPI ````yaml /api-reference/openapi.json get /institutions openapi: 3.0.0 info: description: Documentation of the early finverse services title: Finverse Public termsOfService: https://example.com contact: name: Maintainers email: info@finverse.com license: name: unknown license version: 0.0.1 servers: - url: https://api.prod.finverse.net security: - Oauth2: - test tags: - name: public description: Publicly accessible endpoints x-group: Public - name: customer description: Customer app and institution endpoints x-group: Customer - name: link description: Finverse Link flows x-group: Link - name: login_identity description: Login identity lifecycle and metadata x-group: Login identity - name: accounts description: Accounts, balances, and account numbers x-group: Accounts - name: statements description: Statements and composite statements x-group: Statements - name: transactions description: Transaction history x-group: Transactions - name: identity_income description: Identity and income insights x-group: Identity & income - name: payment_links description: Payment link creation and checkout x-group: Payment links - name: mandates description: Direct debit mandates x-group: Mandates - name: payments description: Payment initiation and status x-group: Payment operations - name: payouts description: Payouts and scheduled payouts x-group: Payouts - name: payment_users description: Payment user profiles x-group: Payment users - name: payment_accounts description: Payment accounts for users x-group: Payment accounts - name: payment_methods description: Stored payment methods x-group: Payment methods - name: bills description: Bill presentment x-group: Bills - name: disputes description: Payment disputes x-group: Disputes - name: ledger description: Ledger and statements x-group: Ledger paths: /institutions: get: tags: - customer summary: Retrieve Institutions list description: >- Retrieve list of all Institutions. **Authorization**: `customer_token` or `link_token` ## Optional parameters You can use the following optional URL parameters to filter the Institutions list returned by Finverse. Example: `GET /institutions?products_supported=ACCOUNT_NUMBERS` # Response fields Full `institutions` array, containing a list of institutions with institution-level metadata. ### login_actions (array) (Informational) Details on dynamic login actions that may be required by the institution (e.g. 2FA). The Finverse Link UI will dynamically display any login actions. There are two types of login actions: \* Actions which require user-input inside the linking flow, e.g. 2FA steps requiring a code-input like SMS OTP or token-based OTP. These are labeled as `type` = `ACTION`. \* Actions which require the user to take action outside the linking flow, e.g. 2FA steps like push notification approval (in the user's bank app). In these cases the action flow provides an informational message to the user to complete the action step. These are labeled as `type` = `INFO`. ### buttons (array) For a given `login_action`, describes the user-facing buttons to display to enable the user to interact with the requested action. Only used for `type` = `ACTION`. ### fields (array) For a given `login_action`, describes the fields which require user-input to enable the user to interact with the requested action. Only used for `type` = `ACTION`. ### options (array) For a `field` with `type`\= `SELECT`, lists the possible options, from which user needs to select one value. ### messages (array) For a given `login_action`, describes the user-facing message(s) to inform the user about what action to take. ### login_details (object) Additional details on login requirements for each institution. ### login_methods (array) Additional details on login methods, containing `login_fields` for each institution. ### login_fields (array) For a given `login_method`, describes the login fields required to authenticate with the institution. These represent the minimum login fields required for all users. Additional fields may be required for some users (those will be dynamically displayed in Finverse Link). ### payment_info (object) Additional details on payment methods supported. operationId: listInstitutions parameters: - description: (Deprecated) The country the institution belongs to name: country in: query schema: type: string - description: The countries the institution belongs to name: countries in: query style: form explode: false schema: type: array items: type: string - description: The products that this institution supports name: products_supported in: query schema: type: string - description: The type of institution name: institution_type in: query schema: type: string enum: - BANK - WALLET - TEST responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/ListInstitutionsResponse' examples: sample: summary: Success (sample) value: - color: '#FFFFFF' countries: - HKG institution_id: hsbc-hk institution_name: HSBC (HK) - Personal institution_type: BANK login_actions: - buttons: - name: buttons_login type: SUBMIT value: Login fields: - label: One Time Password name: otp options: [] placeholder: One Time Password type: INPUT messages: - name: messages_otp_body type: BODY value: >- Enter the OTP (one time password) sent to your mobile phone name: MOBILE_OTP type: ACTION login_details: secretRequired: 'true' secret_required: true login_methods: - id: PASSWORD is_default_method: true login_fields: - key: username name: Username type: text - key: secret name: Memorable answer type: password - key: password name: Password type: password name: Password status: SUPPORTED - id: TOKEN_OTP is_default_method: false login_fields: - key: username name: Username type: text - key: secret name: Memorable answer type: text - key: otp name: Security Code type: text name: Security Code status: ALPHA login_url: https://www.services.online-banking.hsbc.com.hk/ parent_institution_name: HSBC payment_info: currencies_supported: null other_info: bank_code: '004' payments_supported: - MANDATE portal_name: HSBC Personal Account products_supported: - ACCOUNTS - TRANSACTIONS - STATEMENTS - ACCOUNT_NUMBERS - HISTORICAL_TRANSACTIONS - BALANCE_HISTORY - IDENTITY - PAYMENTS status: SUPPORTED status_details: null tags: - real updated_at: '2022-07-19T06:47:43.855Z' user_type: - PERSONAL - INDIVIDUAL - color: '#FFFFFF' countries: - HKG - SGP - PHL institution_id: testbank institution_name: TestBank HK institution_type: BANK login_actions: - buttons: - name: buttons_login type: SUBMIT value: Login fields: - label: One Time Password name: otp options: [] placeholder: One Time Password type: INPUT messages: - name: messages_otp_body_testbank type: BODY value: 'Please enter the OTP. Hint: otp_1234' name: MOBILE_OTP type: ACTION - buttons: - name: buttons_send_notification type: SUBMIT value: Send Notification fields: - label: Select a device name: device options: [] placeholder: Select a device type: SELECT messages: - name: messages_device_selection_approval_title type: BODY value: >- Please select the device to send login approval request to name: DEVICE_SELECTION type: ACTION - buttons: [] fields: [] messages: - name: messages_sent_to_phone type: TITLE value: >- Please approve the login request sent to your phone - name: messages_approval_timeout_default type: BODY value: >- You will have up to 90 seconds to approve the login request name: PUSH_SENT type: INFO - buttons: [] fields: [] messages: - name: messages_sent_to_phone type: TITLE value: >- Please approve the login request sent to your phone - name: messages_sent_to type: BODY value: >- Please approve the login request sent to your phone - name: messages_device type: HIGHLIGHT value: - name: messages_approval_timeout_default type: BODY value: >- You will have up to 90 seconds to approve the login request name: PUSH_SENT type: INFO login_details: infoMessage: >- Use credentials: User ID = usergood | Password = datagood info_message: >- Use credentials: User ID = usergood | Password = datagood login_methods: - id: PASSWORD is_default_method: true login_fields: - key: username name: User ID type: text - key: password name: Password type: password name: Password status: SUPPORTED - id: SECRET is_default_method: false login_fields: - key: username name: User ID type: text - key: password name: Password type: password - key: secret name: Secret type: text name: Password with secret status: SUPPORTED - id: ORGANISATION_ID is_default_method: false login_fields: - key: organisationId name: Organisation ID type: text - key: username name: User ID type: text - key: password name: Password type: password name: Organisation Id status: SUPPORTED login_url: https://woauth.dev.finverse.net parent_institution_name: TEST payment_info: currencies_supported: null other_info: {} payments_supported: - DEBIT_AUTHORIZATION - MANDATE portal_name: Test Bank Personal Account products_supported: - ACCOUNTS - TRANSACTIONS - STATEMENTS - ACCOUNT_NUMBERS - IDENTITY - PAYMENTS status: SUPPORTED status_details: null tags: - test updated_at: '2022-07-19T06:47:43.829Z' user_type: - PERSONAL - INDIVIDUAL '401': description: Error (invalid or missing bearer token) content: application/json: schema: $ref: '#/components/schemas/ErrBodyModelV2' examples: invalid_or_missing_bearer_token: summary: Error (invalid or missing bearer token) value: code: 401 error: code: NOT_AUTHORIZED details: Invalid bearer token error_code: NOT_AUTHORIZED message: >- Authorization failed. Please review authorization requirements in API documentation. request_id: '{unique_id}' type: API_ERROR message: Invalid bearer token '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/BadRequestModelV2' security: - Oauth2: - institution components: schemas: ListInstitutionsResponse: type: array items: $ref: '#/components/schemas/Institution' ErrBodyModelV2: properties: error: $ref: '#/components/schemas/FvErrorModelV2' BadRequestModelV2: properties: error: type: object required: - type - code - error_code - message - request_id properties: code: type: integer example: 40004 details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string request_id: description: The request_id provided in the request header type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR Institution: required: - institution_id - countries - institution_type - products_supported - institution_name - user_type - status - login_details properties: color: type: string example: '#FFFFFF' countries: type: array items: type: string example: - HKG institution_id: type: string example: 123 institution_name: type: string example: Mock Bank institution_type: type: string enum: - BANK - WALLET - TEST example: BANK login_actions: type: array items: $ref: '#/components/schemas/LoginAction' login_details: x-go-type: import: package: gitlab.com/finverse/gitops/applications/api/models/custom type: LoginDetails login_methods: type: array items: $ref: '#/components/schemas/LoginMethod' login_url: type: string example: https://example.com/login parent_institution_name: type: string example: Parent Mock Bank payment_info: $ref: '#/components/schemas/PaymentInfo' portal_name: type: string example: Personal Internet Banking products_supported: type: array items: type: string enum: - ACCOUNTS - TRANSACTIONS - STATEMENTS - ACCOUNT_NUMBERS - IDENTITY - AUTO_DEBIT_SETUP example: - ACCOUNTS - TRANSACTIONS - STATEMENTS - ACCOUNT_NUMBERS - IDENTITY - AUTO_DEBIT_SETUP status: type: string enum: - SUPPORTED - ALPHA - BETA example: SUPPORTED status_details: type: object example: {} tags: type: array items: type: string enum: - real - test example: - real updated_at: type: string format: date-time user_type: type: array items: type: string enum: - PERSONAL - INDIVIDUAL - BUSINESS example: INDIVIDUAL FvErrorModelV2: required: - type - error_code - message - details - request_id properties: details: type: string error_code: type: string example: CREDENTIALS_INVALID message: type: string request_id: description: The request_id provided in the request header type: string type: description: The error type type: string enum: - LINK_ERROR - API_ERROR example: LINKING_ERROR LoginAction: properties: buttons: type: array items: $ref: '#/components/schemas/UserButton' fields: type: array items: $ref: '#/components/schemas/UserField' messages: type: array items: $ref: '#/components/schemas/UserMessage' name: type: string example: MOBILE_OTP type: type: string example: ACTION LoginMethod: properties: id: type: string example: SMS OTP is_default_method: type: boolean example: true nullable: true login_fields: type: array items: $ref: '#/components/schemas/LoginField' name: type: string example: SMS OTP status: type: string enum: - SUPPORTED - ALPHA - BETA example: SUPPORTED PaymentInfo: required: - payments_supported properties: currencies_supported: type: array items: type: string example: - HKD - CNY other_info: $ref: '#/components/schemas/OtherInfo' payments_supported: type: array items: type: string enum: - MANDATE - DEBIT_AUTHORIZATION example: - MANDATE - DEBIT_AUTHORIZATION UserButton: required: - name - value - type properties: name: description: Name identifying the button type: string type: description: 'Type of button. Possible values: `SUBMIT`' type: string example: SUBMIT value: description: Button value to be displayed to the user type: string example: Submit One time password UserField: required: - name - type properties: label: description: User-facing label for the field type: string name: description: Name identifying the field type: string options: description: >- List of possible options, from which user needs to select one value. Only used for field `type` = `SELECT` type: array items: $ref: '#/components/schemas/UserFieldOption' placeholder: description: Initial field value to be displayed to the user type: string type: description: 'Type of field. Possible values: `INPUT`, `SELECT`' type: string example: SELECT UserMessage: required: - name - type - value properties: name: description: The name of the message type: string type: description: >- The type of the message. This will help how the UI renders this text. type: string value: description: The actual text value. type: string LoginField: properties: key: type: string example: password name: type: string example: Password type: description: could be password, text, number type: string example: password OtherInfo: properties: bank_code: type: string UserFieldOption: required: - label - value properties: label: description: User-facing label for the option type: string example: joe-iphone-13 value: description: Value for the option type: string example: Joe's iPhone 13 Pro Max securitySchemes: Oauth2: type: oauth2 flows: clientCredentials: tokenUrl: https://finverse-dev.us.auth0.com/oauth/token scopes: account: Account balance: Balance credit: Credit institution: Institution investment: Investment link: Link test: Test transaction: Transaction ````