FI Request Status

​

Overview

​

Key Use Cases

• Status Monitoring: Track the progress of an FI request from initiation through completion.
• Data Readiness Check: Determine when the financial information is ready to be retrieved using the Get All FI Data API.
• Account-Level Details: Get detailed information about individual accounts linked to the consent, including their data fetch status.
• Error Detection: Identify if any accounts failed to provide data or timed out during the fetch process.

​

Important Notes

• You must provide at least one of the following identifiers: consentId, consentHandle, or sessionId to check the status.
• The API returns comprehensive information about all accounts linked to the consent, including which ones have successfully delivered data.
• Per-account fiStatus values are reported individually in linkRefNumbers; possible values are PENDING, READY, DELIVERED, DENIED, TIMEOUT.
• Partial readiness: the top-level eventStatus is DATA_READY if at least one account is READY or DELIVERED, even when other accounts are still PENDING, DENIED, or TIMEOUT. There is no separate “partial” status — inspect linkRefNumbers to see which accounts are actually available.

​

Authentication

​

Request Body

​

Request Example

{
  "consentId": "84001bb6-b1d0-4443-aeff-dd482255a058",
  "sessionId": "7b863266-fcae-478b-906d-4d69e818fe18"
}

​

Response Parameters

​

Success Response Example

{
  "ver": "1.21.0",
  "status": "success",
  "data": {
    "timestamp": "2025-03-24T17:52:49.213Z",
    "consentHandle": "272a12db-9e4e-4f95-8c48-790f207dedc8",
    "eventType": "DATA",
    "eventStatus": "DATA_READY",
    "consentId": "84001bb6-b1d0-4443-aeff-dd482255a058",
    "vua": "9674987439@onemoney",
    "eventMessage": "Data ready for consent id 84001bb6-b1d0-4443-aeff-dd482255a058",
    "datafetchDate": "2025-03-24T17:52:03.000Z",
    "productID": "TEST1",
    "accountID": "test",
    "fetchType": "ONETIME",
    "consentExpiry": "2025-03-31 17:50:43",
    "sessionId": "7b863266-fcae-478b-906d-4d69e818fe18",
    "dataExpiry": "2025-03-25T17:52:03.000Z",
    "firstTimeFetch": true,
    "linkRefNumbers": [
      {
        "linkRefNumber": "e72534d6-0016-4f0e-9da5-3e05ad405394",
        "fiStatus": "DELIVERED",
        "fipName": "FinShareBankServer",
        "fipId": "finsharebank",
        "maskedAccountNumber": "XXXXXXXX3900"
      },
      {
        "linkRefNumber": "2db448bf-d19a-4f42-928f-1bd4a012000f",
        "fiStatus": "DELIVERED",
        "fipName": "FinShareBankServer",
        "fipId": "finsharebank",
        "maskedAccountNumber": "XXXXXXXX3908"
      }
    ]
  },
  "message": "success"
}

​

Error Responses

​

Invalid Session ID

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:46:57.415Z",
  "errorCode": "InvalidRequest",
  "errorMsg": " [ sessionId must be a valid GUID ] "
}

​

Common Error Scenarios

• InvalidRequest: The request contains invalid data, such as malformed GUID values or missing required parameters.
• InvalidConsentId: The provided consent ID does not exist in the system.
• InvalidSessionId: The provided session ID is not in valid GUID format or does not exist.
• NoDataFound: No FI request has been initiated for the provided identifiers.

​

Rate Limiting

• Rate Limit: 1000 requests per time window
• Headers Returned:
  • X-RateLimit-Limit: Maximum number of requests allowed
  • X-RateLimit-Remaining: Number of requests remaining in current window
  • X-RateLimit-Reset: Unix timestamp when the rate limit resets

​

Usage Flow

1. Initiate FI Request: First, call the FI Request API to initiate the data fetch. Save the returned sessionId.
2. Wait for Processing: Allow some time for the Account Aggregator to fetch data from the Financial Information Providers. This typically takes a few seconds to minutes depending on the number of accounts.
3. Poll Status: Call this API periodically with the sessionId to check the status. Implement exponential backoff for polling (e.g., start with 5 seconds, then 10, 20, etc.).
4. Check Event Status: Monitor the eventStatus field:
   • DATA_READY: at least one account is ready — you can call Get All FI Data, but check linkRefNumbers to know which ones are actually available
   • DATA_DENIED / SESSION_FAILED / SESSION_EXPIRED: terminal failure for this fetch — no data will be returned; surface the failure to the user
   • If none of the above are returned and accounts are still PENDING in linkRefNumbers, continue polling
5. Check Individual Account Status: Review the linkRefNumbers array to see which specific accounts are READY/DELIVERED and which are still PENDING, DENIED, or TIMEOUT.
6. Retrieve Data: Once eventStatus is DATA_READY, use the Get All FI Data API to retrieve the actual financial information.

​

Best Practices

• Polling Strategy: Implement exponential backoff when polling to avoid overwhelming the API. Start with shorter intervals and gradually increase them.
• Timeout Handling: Set a maximum polling duration (e.g., 5 minutes). If data is not ready by then, handle it as a timeout scenario.
• Partial Success: Even if some accounts have TIMEOUT status, others may have DELIVERED. You can still proceed to retrieve data for successfully delivered accounts.
• Data Expiry Awareness: Note the dataExpiry timestamp. Plan to retrieve and process the data before it expires and gets deleted from the system.
• Session ID Persistence: Store the sessionId in your database to enable status checks even if your application restarts.
• Error Recovery: If you receive an error, verify that you’re using the correct identifiers (consentId, sessionId, or consentHandle) and that they are in valid format.
• Account-Level Monitoring: For consents with multiple accounts, monitor each account’s fiStatus individually to provide detailed feedback to users.
• First Fetch Indicator: Use the firstTimeFetch flag to differentiate between initial data retrieval and incremental updates for periodic consents.