Skip to main content
POST
/
fi
/
request
FI Request
curl --request POST \
  --url https://api.example.com/fi/request \
  --header 'Content-Type: <content-type>' \
  --header 'appIdentifier: <appidentifier>' \
  --header 'client_id: <client_id>' \
  --header 'client_secret: <client_secret>' \
  --header 'organisationId: <organisationid>' \
  --data '
{
  "consentId": "<string>",
  "fiDataRangeFrom": "<string>",
  "fiDataRangeTo": "<string>"
}
'
{
  "ver": "<string>",
  "timestamp": "<string>",
  "response": "<string>",
  "data": {
    "consentId": "<string>",
    "sessionId": "<string>"
  }
}

​
Overview

The FI Request API is used to initiate a request for Financial Information (FI) from the Account Aggregator system. This API triggers the data fetch process for accounts associated with an approved consent. The data flow is asynchronous, meaning the financial information is not returned immediately in this API’s response but will be available once the fetch is completed.

​
Key Use Cases

  • Automatic FI Fetch: For automatic fetch types, the FinPro system handles FI requests automatically, so Financial Information Users (FIUs) do not need to explicitly call this API.
  • Periodic/Recurring Fetch: For periodic or recurring fetch types, it is recommended to request incremental data only to optimize data transfer and processing.
  • Custom Date Range: You can optionally specify a custom date range for the financial data you want to fetch, overriding the date range specified in the consent artefact.

​
Important Notes

  • Since the data flow is asynchronous, the FIU will not receive the actual Financial Information (FI) in the response of this API. Instead, use the FI Request Status API to check when the data is ready.
  • If the fiDataRange parameters are not passed, the data is fetched according to the data range specified in the consent artefact.
  • For periodic fetch types, if no date range is specified, incremental data is fetched automatically.

​
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

​
consentId
string
required
The unique consent identifier provided by the Account Aggregator after the user has approved the consent. This ID links the FI request to a specific approved consent.
​
fiDataRangeFrom
string
The start date from when the financial information statement is required. Must be in ISO 8601 date format with UTC timezone (e.g., 2021-05-01T16:49:48.297Z). If not provided, the start date from the consent artefact will be used.
​
fiDataRangeTo
string
The end date until when the financial information statement is required. Must be in ISO 8601 date format with UTC timezone (e.g., 2022-05-06T06:33:00.000Z). This value must be less than or equal to the current UTC timestamp. If not provided, the end date from the consent artefact will be used.

​
Request Example

{
  "consentId": "54450ac0-8bcb-4b9c-ad74-29b4fabe18f7",
  "fiDataRangeFrom": "2021-05-01T16:49:48.297Z",
  "fiDataRangeTo": "2022-05-06T06:33:00.000Z"
}

​
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.
​
timestamp
string
required
The timestamp when the API response was generated, in UTC time format. This can be used for logging and debugging purposes.
​
response
string
required
The status of the API call. Returns "ok" when the FI request has been successfully initiated.
​
data
object
required
Contains the essential identifiers for tracking the FI request.

​
Success Response Example

{
  "ver": "1.1.2",
  "timestamp": "2022-05-19T09:16:48.811Z",
  "response": "ok",
  "data": {
    "consentId": "54450ac0-8bcb-4b9c-ad74-29b4fabe18f7",
    "sessionId": "9d2b0920-389a-47cb-bd8f-d931dc0e801b"
  }
}

​
Error Responses

When the provided consent ID does not exist in the system: 
{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:46:13.293Z",
  "errorCode": "InvalidConsentId",
  "errorMsg": "Consent ID does not exist."
}
HTTP Status Code: 400 Bad Request

​
Common Error Scenarios

  • InvalidConsentId: The provided consent ID does not exist in the FinPro system or has been deleted.
  • InvalidRequest: The request body contains invalid data, such as malformed date formats or missing required fields.
  • ConsentExpired: The consent has expired and can no longer be used to fetch financial information.
  • ConsentRevoked: The user has revoked the consent, and it can no longer be used for data fetching.

​
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. Obtain Consent: Before calling this API, ensure you have successfully obtained user consent and received a consentId from the Account Aggregator.
  2. Initiate FI Request: Call this API with the consentId to initiate the financial information fetch process. Optionally, specify custom date ranges if needed.
  3. Store Session ID: Save the returned sessionId from the response. You will need this to check the status of the data fetch.
  4. Poll Status: Use the FI Request Status API with the sessionId to periodically check when the data is ready for retrieval.
  5. Retrieve Data: Once the status indicates the data is ready, use the Get All FI Data API to retrieve the actual financial information.

​
Best Practices

  • Incremental Data Fetching: For periodic/recurring consents, always request incremental data by specifying appropriate date ranges. This reduces processing time and bandwidth usage.
  • Session ID Management: Always store the sessionId returned in the response. This is crucial for tracking the status of your data fetch request.
  • Error Handling: Implement robust error handling to gracefully manage scenarios where the consent ID is invalid, expired, or revoked.
  • Asynchronous Processing: Since this API is asynchronous, implement a polling mechanism or webhook handler to know when the data is ready. Do not expect immediate data availability.
  • Date Range Validation: When specifying custom date ranges, ensure the fiDataRangeTo is not in the future and falls within the consent’s approved date range.
  • Rate Limit Management: Monitor the rate limit headers and implement backoff strategies to avoid hitting rate limits.