FI Request Status

Overview

The FI Request Status API allows you to check the current status of a financial information (FI) request that was initiated using the FI Request API. Since the FI data fetch process is asynchronous, this API is essential for determining when the requested financial data has been successfully retrieved and is ready for download.

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.
Different accounts may have different statuses (DELIVERED, PENDING, TIMEOUT), which are reported individually in the response.

Authentication

This API requires authentication using the following headers:

client_id

string

required

Your unique client identifier provided by FinPro during onboarding. This ID is used to authenticate your application.

client_secret

string

required

Your confidential client secret key provided by FinPro. This must be kept secure and never exposed in client-side code.

appIdentifier

string

required

The unique identifier for your application (e.g., your application’s package name or bundle ID). This helps FinPro identify which application is making the request.

organisationId

string

required

Your organization’s unique identifier assigned by FinPro. This identifies your organization in the FinPro system.

Content-Type

string

required

Must be set to application/json to indicate that the request body contains JSON data.

Request Body

At least one of the following parameters must be provided:

The unique consent identifier provided by the Account Aggregator. Use this to check the status of all FI requests associated with this consent.

The unique consent handle identifier. This is an alternative identifier for the consent that can be used instead of consentId.

sessionId

string

The unique session identifier returned in the FI Request API response. Use this to check the status of a specific FI request session.

Request Example

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

Response Parameters

ver

string

required

The version of the API that processed the request. This helps track which version of the API handled your request.

status

string

required

The overall status of the API response. Returns "success" when the status check is successful, or "failure" if there was an error.

data

object

required

Contains comprehensive status information about the FI request.

Show data properties

timestamp

string

required

The timestamp when the status was checked, in UTC time format. This indicates when the status information was generated.

The unique consent handle identifier associated with this FI request. This is an alternative identifier for the consent.

eventType

string

required

The type of event being reported. For FI requests, this will be "DATA" to indicate it’s a data fetch event.

eventStatus

string

required

The current status of the FI data fetch event. Possible values:

DATA_READY: The financial information has been successfully fetched and is ready for retrieval
PENDING: The data fetch is still in progress
TIMEOUT: The data fetch operation has timed out

The unique consent identifier for which the status is being checked. This confirms which consent the status information relates to.

vua

string

required

The Virtual User Address (VUA) associated with the consent. This is the user’s identifier in the Account Aggregator ecosystem.

eventMessage

string

required

A human-readable message describing the current status of the event. This provides additional context about the data fetch status.

datafetchDate

string

required

The timestamp when the data was fetched from the Financial Information Providers (FIPs), in UTC time format.

productID

string

required

The product identifier associated with the consent. This identifies the financial product or service for which data was requested.

accountID

string

required

The account identifier associated with the consent. This identifies the specific account configuration used for the consent.

fetchType

string

required

The type of data fetch configured in the consent. Possible values:

ONETIME: Data is fetched only once
PERIODIC: Data is fetched periodically at scheduled intervals

The expiry timestamp of the consent. After this time, the consent can no longer be used to fetch financial information.

sessionId

string

required

The unique session identifier for this FI request. This can be used to track this specific data fetch request.

dataExpiry

string

required

The expiry timestamp of the fetched data, calculated based on the data life defined in the consent. After this time, the data will be deleted from FinPro’s systems for security and compliance reasons.

firstTimeFetch

boolean

required

Indicates whether this is the first time data is being fetched for this consent. Returns true for the initial fetch, false for subsequent incremental fetches.

linkRefNumbers

array

required

An array of objects containing information about individual accounts linked to the consent. Each object provides details about a specific account’s data fetch status.

Show linkRefNumbers item properties

linkRefNumber

string

required

The unique linked reference number for the account. This identifier is used to retrieve data for this specific account.

fiStatus

string

required

The status of financial information retrieval for this specific account. Possible values:

DELIVERED: Data has been successfully retrieved for this account
PENDING: Data fetch is still in progress for this account
TIMEOUT: Data fetch has timed out for this account

fipName

string

required

The name of the Financial Information Provider (FIP) or bank that holds this account. This is the institution from which data was requested.

fipId

string

required

The unique identifier of the Financial Information Provider in the Account Aggregator ecosystem.

maskedAccountNumber

string

required

The masked account number for privacy and security. Typically shows only the last few digits of the actual account number (e.g., XXXXXXXX3900).

message

string

required

A summary message indicating success or failure of the status check operation.

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

When the provided session ID is not a valid GUID format:

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

HTTP Status Code: 400 Bad Request

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

This API is subject to rate limiting to ensure fair usage and system stability:

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

If you exceed the rate limit, you will receive a 429 Too Many Requests response.

Usage Flow

Initiate FI Request: First, call the FI Request API to initiate the data fetch. Save the returned sessionId.
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.
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.).
Check Event Status: Monitor the eventStatus field:
- When DATA_READY: Proceed to retrieve the data using Get All FI Data API
- When PENDING: Continue polling
- When TIMEOUT: Handle the timeout scenario (some accounts may have timed out)
Check Individual Account Status: Review the linkRefNumbers array to see which specific accounts have DELIVERED their data and which may have PENDING or TIMEOUT status.
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.

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

Overview

Key Use Cases

Important Notes

Authentication

Request Body

Request Example

Response Parameters

Success Response Example

Error Responses

Invalid Session ID

Common Error Scenarios

Rate Limiting

Usage Flow

Best Practices

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

​Overview

​Key Use Cases

​Important Notes

​Authentication

​Request Body

​Request Example

​Response Parameters

​Success Response Example

​Error Responses

​Invalid Session ID

​Common Error Scenarios

​Rate Limiting

​Usage Flow

​Best Practices

Overview

Key Use Cases

Important Notes

Authentication

Request Body

Request Example

Response Parameters

Success Response Example

Error Responses

Invalid Session ID

Common Error Scenarios

Rate Limiting

Usage Flow

Best Practices