> ## 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. # Get login identity > Retrieve information about a Login Identity, including its authentication and data retrieval status. Does not contain any sensitive user data. Note: a Login Identity represents a unique financial institution authenticated account linked by the end-user. An end-user who links multiple Institutions (or multiple authenticated accounts at the same Institution), will have a distinct Login Identity for each linked account. **Authorization:** `login_identity_token` ### institution Summary Institutions object. See `GET /institutions` for object details. ### login_identity Full `login_identity` object, containing metadata and status information. #### authentication_status Provides details on the authentication status of the Login Identity. #### error Provides additional details on any error. Empty if no error has occurred. #### product_status Provides details on the data retrieval status of the Login Identity, broken down by Finverse Products. We recommend using this field to determine when to fetch data from Finverse's product endpoints (if not using webhooks). Products: `accounts`, `account_numbers`, `balance_history`, `historical_transactions`, `identity`, `income_estimation`,`online_transactions`, `statements`. Note: Requesting `GET /transactions` fetches both `online_transactions` and `historical_transactions` (if available). Online transactions refer to transaction records retrieved directly from the institution (sometimes covering only a limited time-period); historical transactions refer to additional records which Finverse extracts from `statements`. `product_status` contains a list of Products, each returning the following status object. Each Product will only be listed once data retrieval has started for the Product. #### Refresh Provides details on the ability to refresh data for a Login Identity (i.e. retrieve new data from the institution without any additional user action). Will only be returned if user consented to automated data refreshes. Refer to section `12 - Data Refresh & Relinking` for additional guidance on refresh & relinking. View More #### status_details Provides details on the most recent event involving this Login Identity (e.g. authentication, data retrieval, unlinking). See `GET /login_identity/{login_identity_id}/history` to request the full events list involving a Login Identity. ## OpenAPI ````yaml /api-reference/openapi.json get /login_identity 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: /login_identity: get: tags: - login_identity summary: Get login identity description: >- Retrieve information about a Login Identity, including its authentication and data retrieval status. Does not contain any sensitive user data. Note: a Login Identity represents a unique financial institution authenticated account linked by the end-user. An end-user who links multiple Institutions (or multiple authenticated accounts at the same Institution), will have a distinct Login Identity for each linked account. **Authorization:** `login_identity_token` ### institution Summary Institutions object. See `GET /institutions` for object details. ### login_identity Full `login_identity` object, containing metadata and status information. #### authentication_status Provides details on the authentication status of the Login Identity. #### error Provides additional details on any error. Empty if no error has occurred. #### product_status Provides details on the data retrieval status of the Login Identity, broken down by Finverse Products. We recommend using this field to determine when to fetch data from Finverse's product endpoints (if not using webhooks). Products: `accounts`, `account_numbers`, `balance_history`, `historical_transactions`, `identity`, `income_estimation`,`online_transactions`, `statements`. Note: Requesting `GET /transactions` fetches both `online_transactions` and `historical_transactions` (if available). Online transactions refer to transaction records retrieved directly from the institution (sometimes covering only a limited time-period); historical transactions refer to additional records which Finverse extracts from `statements`. `product_status` contains a list of Products, each returning the following status object. Each Product will only be listed once data retrieval has started for the Product. #### Refresh Provides details on the ability to refresh data for a Login Identity (i.e. retrieve new data from the institution without any additional user action). Will only be returned if user consented to automated data refreshes. Refer to section `12 - Data Refresh & Relinking` for additional guidance on refresh & relinking. View More #### status_details Provides details on the most recent event involving this Login Identity (e.g. authentication, data retrieval, unlinking). See `GET /login_identity/{login_identity_id}/history` to request the full events list involving a Login Identity. operationId: getLoginIdentity responses: '200': description: Successful content: application/json: schema: $ref: '#/components/schemas/GetLoginIdentityByIdResponse' examples: success: summary: Success value: institution: countries: - HKG - SGP - PHL institution_id: testbank institution_name: TestBank HK portal_name: Test Bank Personal Account login_identity: authentication_id: '0' authentication_status: last_successful_update: '2021-12-03T02:08:23.087Z' last_update: '2021-12-03T02:08:23.087Z' status: AUTHENTICATED status_details: AUTHENTICATED billing_details: billed_products: null created_at: '2021-12-03T02:07:58.103Z' customer_app_id: '{{customer_app_id}}' error: {} first_success: '2021-12-03T02:07:58.103Z' institution_id: testbank last_session_id: 01FZDHPQ5NZSMBEZ2RB6J5PQC3 last_success: '2021-12-03T02:08:23.034Z' linking_attempt_id: '0' login_identity_id: 01FNZ0RP2MWD0SNFBXT8VJ65PE login_methods_available: {} permissions: null permissions_expiry_date: '2021-12-03T02:07:58.103Z' permissions_grant_date: '2021-12-03T02:07:58.103Z' product_status: account_numbers: last_successful_update: '2021-12-03T02:08:25.189Z' last_update: '2021-12-03T02:08:25.189Z' status: SUCCESS status_details: ACCOUNT_NUMBERS_RETRIEVED accounts: last_successful_update: '2021-12-03T02:08:25.050Z' last_update: '2021-12-03T02:08:25.050Z' status: SUCCESS status_details: ACCOUNTS_RETRIEVED balance_history: status: SUCCESS status_details: BALANCE_HISTORY_RETRIEVED historical_transactions: last_update: '2021-12-03T02:08:33.698Z' status: SUCCESS status_details: HISTORICAL_TRANSACTIONS_RETRIEVED identity: last_successful_update: '2021-12-03T02:08:27.898Z' last_update: '2021-12-03T02:08:27.898Z' status: SUCCESS status_details: IDENTITY_RETRIEVED online_transactions: last_successful_update: '2021-12-03T02:08:26.790Z' last_update: '2021-12-03T02:08:26.790Z' status: SUCCESS status_details: ONLINE_TRANSACTIONS_RETRIEVED statements: last_successful_update: '2021-12-03T02:08:29.092Z' last_update: '2021-12-03T02:08:29.092Z' status: SUCCESS status_details: STATEMENTS_RETRIEVED refresh: credentials_stored: true refresh_allowed: true session_status: COMPLETED status: DATA_RETRIEVAL_COMPLETE status_details: event_date: '2021-12-03T02:08:33.794Z' event_name: BALANCE_HISTORY_RETRIEVED updated_at: '2021-12-03T02:08:33.811Z' user_id: 01FN8TJ92X38QF7B4N5HRP8X3K webhook: https://example.com/callback failed_data_retrieval: summary: Failed data retrieval value: institution: countries: - HKG - IDN - MYS - PHL - SGP - THA - VNM institution_id: testbank institution_name: Testbank portal_name: Testbank Online Banking login_identity: authentication_id: '0' authentication_status: last_successful_update: '2025-04-01T09:42:29.367Z' last_update: '2025-04-01T09:42:29.367Z' status: AUTHENTICATED status_details: AUTHENTICATED billing_details: billed_products: null created_at: '2025-04-01T09:42:25.580Z' customer_app_id: 01F78EFQVCSKYVV154ZWBTAZ5D error: code: 11007 details: >- An error occurred while retrieving data from the institution. Please try again in a few days. message: Data retrieval error type: DATA_RETRIEVE_FAILED first_success: '2025-04-01T09:42:25.523Z' institution_id: testbank last_session_id: 01JQRBP3FKQ7T2CQVTCPM8Y83Y last_success: '2025-04-01T09:42:37.853Z' linking_attempt_id: '0' login_identity_id: 01JQRBP3FKQ7T2CQVTCMG4ASNG login_methods_available: {} permissions: null permissions_expiry_date: '2025-04-01T09:42:25.523Z' permissions_grant_date: '2025-04-01T09:42:25.523Z' product_status: account_numbers: last_successful_update: '2025-04-01T09:42:30.022Z' last_update: '2025-04-01T09:42:30.022Z' status: SUCCESS status_details: ACCOUNT_NUMBERS_RETRIEVED accounts: last_successful_update: '2025-04-01T09:42:29.959Z' last_update: '2025-04-01T09:42:29.959Z' status: SUCCESS status_details: ACCOUNTS_RETRIEVED balance_history: last_update: '2025-04-01T09:42:37.604Z' status: WARNING status_details: BALANCE_HISTORY_PARTIALLY_RETRIEVED card_details: last_update: '2025-04-01T09:42:34.793Z' status: IN_PROGRESS status_details: CREDIT_CARD_DETAILS_RETRIEVAL_STARTED historical_transactions: last_update: '2025-04-01T09:42:37.684Z' status: NOT_AVAILABLE status_details: STATEMENTS_NOT_AVAILABLE identity: last_update: '2025-04-01T09:42:35.257Z' status: ERROR status_details: IDENTITY_RETRIEVAL_FAILED income_estimation: last_update: '2025-04-01T09:42:37.871Z' status: WARNING status_details: INCOME_ESTIMATION_NOT_FOUND online_transactions: last_update: '2025-04-01T09:42:34.749Z' status: WARNING status_details: ONLINE_TRANSACTIONS_NOT_FOUND statements: last_update: '2025-04-01T09:42:37.712Z' status: WARNING status_details: STATEMENTS_NOT_FOUND refresh: credentials_stored: false refresh_allowed: false session_status: COMPLETED status: DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL status_details: event_date: '2025-04-01T09:42:37.871Z' event_name: INCOME_ESTIMATION_NOT_FOUND updated_at: '2025-04-01T09:42:37.875Z' user_id: 01FQKAATDH2C25P9C3MPTRT5Q7 webhook: https://example.com/callback '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/BadRequestModelV2' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/BadRequestModelV2' security: - Oauth2: - loginIdentity:self components: schemas: GetLoginIdentityByIdResponse: properties: institution: $ref: '#/components/schemas/InstitutionShort' login_identity: $ref: '#/components/schemas/LoginIdentity' 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 InstitutionShort: properties: countries: type: array items: type: string example: - HKG institution_id: type: string example: 123 institution_name: type: string example: Mock Bank portal_name: type: string example: Personal Internet Banking LoginIdentity: required: - user_id - customer_app_id - institution_id properties: authentication_id: description: a successful login attempt id which is unique per login_identity type: string example: 123 authentication_status: $ref: '#/components/schemas/ProductStatus' billing_details: $ref: '#/components/schemas/LoginIdentityBillingDetails' description: Reserved for future use created_at: type: string format: date-time description: >- Timestamp when the Login Identity was first created (via `POST /link/token` request to generate a Link Token) customer_app_id: type: string format: ulid description: Finverse Customer ID for this Customer error: $ref: '#/components/schemas/LoginIdentityError' description: Empty if no error has occurred. first_success: type: string format: date-time description: >- Timestamp of the first successful authentication of the Login Identity institution_id: type: string example: 123 description: Finverse Institution ID for this Login Identity last_session_id: type: string format: ulid last_success: type: string format: date-time description: >- Timestamp of the last successful authentication or data retrieval of the Login Identity linking_attempt_id: description: a login attempt id which is unique per login_identity type: string example: 123 login_identity_id: type: string format: ulid description: >- Finverse Login Identity ID for this Login Identity. Always unique. Linking the same account at the same institution twice will result in two Login Identities with different IDs (use Refresh/Relink methods to refresh data for a Login Identity without updating the ID). login_methods_available: $ref: '#/components/schemas/LoginIdentityLoginMethodsAvailable' description: Reserved for future use permissions: type: array items: type: string description: Reserved for future use permissions_expiry_date: type: string format: date-time description: Reserved for future use permissions_grant_date: type: string format: date-time description: Reserved for future use product_status: $ref: '#/components/schemas/AllProductStatus' refresh: $ref: '#/components/schemas/RefreshData' session_status: type: string example: COMPLETED description: >- Status of the most recent Institution linking session. Possible values: `IN_PROGRESS`, `COMPLETED`, `UNLINKED`. "COMPLETED" means data retrieval for all products has finished (can be successfully or with errors); this field can be used to determine when to fetch data from Finverse's product endpoints (if not using `product_status`, or webhooks instead). status: type: string example: LINKING description: >- Summary status of the Login Identity. Possible values: `LINKING`, `AUTHENTICATING`, `DATA_RETRIEVAL_IN_PROGRESS`, `DATA_AVAILABLE`, `DATA_RETRIEVAL_COMPLETE`, `DATA_RETRIEVAL_PARTIALLY_SUCCESSFUL`, `ERROR`, `REFRESHING`, `UNLINKED`, `UNLINK_SUCCEEDED`, `UNLINK_FAILED`, `UNKNOWN`. We do not recommend using this field to determine when to fetch data from Finverse's product endpoints (use `product_status`, `session_status`, or webhooks instead). status_details: $ref: '#/components/schemas/LoginIdentityStatusDetails' updated_at: type: string format: date-time description: >- Timestamp of the last event involving this Login Identity (e.g. authentication, data retrieval, unlinking) user_id: type: string example: form_post description: >- Customer's User ID for this Login Identity, as provided to Finverse during first-time linking (in the `POST /link/token` request to generate a Link Token). This allows Customers to map Finverse's `login_identity_id` to Customer's `user_id` schema. Each `user_id` can link multiple Login Identities. We recommend that Customers do not include any sensitive data in `user_id`. webhook: type: string format: uri example: https://auth.example.com/callback description: >- (not yet supported) The URL specified for receiving webhooks for this Login Identity ProductStatus: properties: last_successful_update: type: string format: date-time example: '2021-02-01T10:01:02.333Z' nullable: true description: Timestamp of the last successful update of the Product last_update: type: string format: date-time example: '2021-02-01T10:01:02.333Z' nullable: true description: Timestamp of the last status event involving the Product status: description: >- Status of the Product Possible values: `IN_PROGRESS`, `SUCCESS`, `WARNING`, `ERROR`, `NOT_SUPPORTED`, `NOT_AVAILABLE`, `TEMPORARILY_UNAVAILABLE_FOR_INSTITUTION`,`UNKNOWN` type: string example: IN_PROGRESS, SUCCESS, PARTIAL_ERROR, WARNING, ERROR status_details: description: >- Additional details on the status of the Product. See documentation on Webhooks (Data webhook events) for explanations of status meanings. Possible values: `[PRODUCT]_RETRIEVAL_STARTED`, `[PRODUCT]_RETRIEVED`, `[PRODUCT]_PARTIALLY_RETRIEVED`, `[PRODUCT]_RETRIEVAL_FAILED`, `[PRODUCT]_NOT_FOUND`, `[PRODUCT]_NOT_SUPPORTED`, `[PRODUCT]_TEMPORARILY_UNAVAILABLE_FOR_INSTITUTION`, `[PRODUCT]_COMPLETED`,`[PRODUCT]_PARTIALLY_COMPLETED`, `[PRODUCT]_FAILED` type: string example: AUTHENTICATION_INITIALIZED LoginIdentityBillingDetails: properties: billed_products: type: array items: type: string LoginIdentityError: type: object properties: code: type: integer details: type: string example: Credentials are invalid. Please try again. message: type: string example: Credentials invalid type: type: string example: INVALID_CREDENTIALS LoginIdentityLoginMethodsAvailable: type: object properties: havePassword: type: boolean haveSecret: type: boolean AllProductStatus: properties: account_numbers: $ref: '#/components/schemas/ProductStatus' accounts: $ref: '#/components/schemas/ProductStatus' balance_history: $ref: '#/components/schemas/ProductStatus' card_details: $ref: '#/components/schemas/ProductStatus' historical_transactions: $ref: '#/components/schemas/ProductStatus' identity: $ref: '#/components/schemas/ProductStatus' income_estimation: $ref: '#/components/schemas/ProductStatus' online_transactions: $ref: '#/components/schemas/ProductStatus' payments: $ref: '#/components/schemas/ProductStatus' statements: $ref: '#/components/schemas/ProductStatus' RefreshData: type: object required: - credentials_stored - refresh_allowed properties: credentials_stored: type: boolean description: >- Indicates whether Finverse has stored user credentials (only with user consent). refresh_allowed: type: boolean description: >- Indicates whether a refresh request is allowed. Refresh is generally allowed if credentials have been stored and no 2FA is expected for this login identity or institution. LoginIdentityStatusDetails: properties: event_date: type: string format: date-time description: >- See `GET /login_identity/{login_identity_id}/history` for field details event_name: type: string description: Same as above 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 ````