> ## 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. # Relink v2 > Create a new link using an existing LIID ## OpenAPI ````yaml /api-reference/openapi.json post /link/relink/{loginIdentityId} 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: /link/relink/{loginIdentityId}: post: tags: - link summary: Relink v2 description: Create a new link using an existing LIID operationId: relinkV2 parameters: - description: The login identity id name: loginIdentityId in: path required: true schema: type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiRelinkRequest' description: Request body for relinking and submitting credentials required: true responses: '200': description: Service Okay content: application/json: schema: $ref: '#/components/schemas/GetLoginIdentityByIdResponse' '400': description: Invalid Request content: application/json: schema: $ref: '#/components/schemas/ErrBodyModel' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ErrBodyModel' security: - Oauth2: - relinkApi:create components: schemas: ApiRelinkRequest: required: - consent - encrypted_credentials properties: consent: type: boolean encrypted_credentials: $ref: '#/components/schemas/EncryptedPayload' store_credential: type: boolean GetLoginIdentityByIdResponse: properties: institution: $ref: '#/components/schemas/InstitutionShort' login_identity: $ref: '#/components/schemas/LoginIdentity' ErrBodyModel: properties: error: $ref: '#/components/schemas/FvErrorModel' EncryptedPayload: required: - ciphertext - initializationVector - messageAuthenticationCode - envelopeEncryptionKey - keyId properties: ciphertext: description: The credential payload encrypted with AES (base64) type: string envelopeEncryptionKey: description: The AES key encrypted with an RSA pubkey (base64) type: string initializationVector: description: The 16 byte IV used w/ AES (base64) type: string keyId: description: The identifier of the public key used to encrypt the AES key type: string messageAuthenticationCode: description: The MAC to verify AES decryption validity type: string 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 FvErrorModel: required: - type - code - error_code - message - details - request_id properties: code: type: string example: CREDENTIALS_INVALID 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 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 ````