> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.
# FI Request Status
> Check the status of a financial information request and determine when data is ready for retrieval.
## 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.
* 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
This API requires authentication using the following headers:
Your unique client identifier provided by FinPro during onboarding. This ID is used to authenticate your application.
Your confidential client secret key provided by FinPro. This must be kept secure and never exposed in client-side code.
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.
Your organization's unique identifier assigned by FinPro. This identifies your organization in the FinPro system.
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`.
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
```json theme={null}
{
"consentId": "84001bb6-b1d0-4443-aeff-dd482255a058",
"sessionId": "7b863266-fcae-478b-906d-4d69e818fe18"
}
```
## Response Parameters
The version of the API that processed the request. This helps track which version of the API handled your request.
The overall status of the API response. Returns `"success"` when the status check is successful, or `"failure"` if there was an error.
Contains comprehensive status information about the FI request.
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.
The type of event being reported. For FI requests, this will be `"DATA"` to indicate it's a data fetch event.
Aggregate status across all accounts linked to the consent. Possible values:
* `DATA_READY`: at least one account is `READY` or `DELIVERED` (returned even if other accounts are still pending, denied, or timed out)
* `DATA_DENIED`: no account is ready/delivered and at least one is `DENIED`
* `SESSION_FAILED`: no account is ready/delivered and at least one is `TIMEOUT`
* `SESSION_EXPIRED`: no account has reached a terminal state (default fallback)
To distinguish a fully-ready fetch from a partial one, count `READY`/`DELIVERED` entries in `linkRefNumbers` against the total.
The unique consent identifier for which the status is being checked. This confirms which consent the status information relates to.
The Virtual User Address (VUA) associated with the consent. This is the user's identifier in the Account Aggregator ecosystem.
A human-readable message describing the current status of the event. This provides additional context about the data fetch status.
The timestamp when the data was fetched from the Financial Information Providers (FIPs), in UTC time format.
The product identifier associated with the consent. This identifies the financial product or service for which data was requested.
The account identifier associated with the consent. This identifies the specific account configuration used for the consent.
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.
The unique session identifier for this FI request. This can be used to track this specific data fetch request.
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.
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.
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.
The unique linked reference number for the account. This identifier is used to retrieve data for this specific account.
The per-account FI fetch status. Possible values:
* `PENDING`: initial state; awaiting notification from the AA
* `READY`: data is available at the FIP and can be fetched
* `DELIVERED`: data has been fetched and stored by FinPro
* `DENIED`: the FIP/AA reported denial for this account
* `TIMEOUT`: the AA did not respond within the timeout window
Both `READY` and `DELIVERED` count as "ready" for the purposes of the top-level `eventStatus`.
The name of the Financial Information Provider (FIP) or bank that holds this account. This is the institution from which data was requested.
The unique identifier of the Financial Information Provider in the Account Aggregator ecosystem.
The masked account number for privacy and security. Typically shows only the last few digits of the actual account number (e.g., `XXXXXXXX3900`).
A summary message indicating success or failure of the status check operation.
### Success Response Example
```json theme={null}
{
"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:
```json theme={null}
{
"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
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.
## OpenAPI
````yaml POST /consent/firequest/status
openapi: 3.0.3
info:
title: FinPro API
description: MoneyOne FinPro - Account Aggregator FIU Platform APIs
version: 1.21.0
servers:
- url: '{baseUrl}'
description: FinPro API Server
variables:
baseUrl:
default: https://scramblerpay-uat.moneyone.in
description: API Base URL - change this to your environment
security:
- clientId: []
clientSecret: []
organisationId: []
appIdentifier: []
paths:
/consent/firequest/status:
post:
tags:
- Data Retrieval
summary: FI Request Status
description: >-
Check the status of a financial information request and determine when
data is ready for retrieval. 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. You must provide at least one of the following identifiers:
consentId, consentHandle, or sessionId.
operationId: getFIRequestStatus
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FIRequestStatusRequest'
example:
consentId: 84001bb6-b1d0-4443-aeff-dd482255a058
sessionId: 7b863266-fcae-478b-906d-4d69e818fe18
responses:
'200':
description: FI request status retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/FIRequestStatusResponse'
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
'400':
description: Bad Request - Invalid data or validation failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
ver: 1.21.0
timestamp: '2025-10-01T11:46:57.415Z'
errorCode: InvalidRequest
errorMsg: ' [ sessionId must be a valid GUID ] '
'401':
description: Authentication Failed - Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'429':
description: >-
Too Many Requests - Rate limit exceeded (1000 requests per time
window)
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- clientId: []
clientSecret: []
organisationId: []
appIdentifier: []
components:
schemas:
FIRequestStatusRequest:
type: object
description: >-
Request body for checking FI request status. At least one of consentId,
consentHandle, or sessionId must be provided.
properties:
consentId:
type: string
format: uuid
description: >-
The unique consent identifier provided by the Account Aggregator.
Use this to check the status of all FI requests associated with this
consent.
consentHandle:
type: string
format: uuid
description: >-
The unique consent handle identifier. This is an alternative
identifier for the consent that can be used instead of consentId.
sessionId:
type: string
format: uuid
description: >-
The unique session identifier returned in the FI Request API
response. Use this to check the status of a specific FI request
session.
FIRequestStatusResponse:
type: object
description: Response containing the status of a financial information request.
properties:
ver:
type: string
description: The version of the API that processed the request.
status:
type: string
description: >-
The overall status of the API response. Returns 'success' when the
status check is successful, or 'failure' if there was an error.
data:
$ref: '#/components/schemas/FIRequestStatusData'
message:
type: string
description: >-
A summary message indicating success or failure of the status check
operation.
ErrorResponse:
type: object
properties:
ver:
type: string
description: API version
timestamp:
type: string
format: date-time
description: When the error occurred
errorCode:
type: string
description: Error category code
errorMsg:
type: string
description: Detailed error message
status:
type: string
description: FinPro-specific error code (FPxxxx format)
FIRequestStatusData:
type: object
description: Contains comprehensive status information about the FI request.
properties:
timestamp:
type: string
format: date-time
description: The timestamp when the status was checked, in UTC time format.
consentHandle:
type: string
format: uuid
description: >-
The unique consent handle identifier associated with this FI
request.
eventType:
type: string
description: >-
The type of event being reported. For FI requests, this will be
'DATA' to indicate it is a data fetch event.
eventStatus:
type: string
enum:
- DATA_READY
- PENDING
- TIMEOUT
description: >-
The current status of the FI data fetch event. DATA_READY means the
financial information has been successfully fetched and is ready for
retrieval. PENDING means the data fetch is still in progress.
TIMEOUT means the data fetch operation has timed out.
consentId:
type: string
format: uuid
description: The unique consent identifier for which the status is being checked.
vua:
type: string
description: The Virtual User Address (VUA) associated with the consent.
eventMessage:
type: string
description: A human-readable message describing the current status of the event.
datafetchDate:
type: string
format: date-time
description: >-
The timestamp when the data was fetched from the Financial
Information Providers (FIPs), in UTC time format.
productID:
type: string
description: The product identifier associated with the consent.
accountID:
type: string
description: The account identifier associated with the consent.
fetchType:
type: string
enum:
- ONETIME
- PERIODIC
description: >-
The type of data fetch configured in the consent. ONETIME means data
is fetched only once. PERIODIC means data is fetched periodically at
scheduled intervals.
consentExpiry:
type: string
description: >-
The expiry timestamp of the consent. After this time, the consent
can no longer be used to fetch financial information.
sessionId:
type: string
format: uuid
description: The unique session identifier for this FI request.
dataExpiry:
type: string
format: date-time
description: >-
The expiry timestamp of the fetched data. After this time, the data
will be deleted from FinPro systems for security and compliance
reasons.
firstTimeFetch:
type: boolean
description: >-
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:
type: array
description: >-
An array of objects containing information about individual accounts
linked to the consent.
items:
$ref: '#/components/schemas/LinkRefNumberItem'
LinkRefNumberItem:
type: object
description: Information about an individual account linked to the consent.
properties:
linkRefNumber:
type: string
format: uuid
description: >-
The unique linked reference number for the account. This identifier
is used to retrieve data for this specific account.
fiStatus:
type: string
enum:
- DELIVERED
- PENDING
- TIMEOUT
description: >-
The status of financial information retrieval for this specific
account. DELIVERED means data has been successfully retrieved.
PENDING means data fetch is still in progress. TIMEOUT means data
fetch has timed out for this account.
fipName:
type: string
description: >-
The name of the Financial Information Provider (FIP) or bank that
holds this account.
fipId:
type: string
description: >-
The unique identifier of the Financial Information Provider in the
Account Aggregator ecosystem.
maskedAccountNumber:
type: string
description: >-
The masked account number for privacy and security. Typically shows
only the last few digits of the actual account number (e.g.,
XXXXXXXX3900).
securitySchemes:
clientId:
type: apiKey
in: header
name: client_id
description: Your unique client identifier provided by MoneyOne during FIU onboarding
clientSecret:
type: apiKey
in: header
name: client_secret
description: Your confidential client secret provided by MoneyOne
organisationId:
type: apiKey
in: header
name: organisationId
description: Your organization's unique identifier in the FinPro system
appIdentifier:
type: apiKey
in: header
name: appIdentifier
description: Application-specific identifier for tracking API calls
````