Finpass API Collection
  1. Account Aggregator
  • Introduction
  • Bank Statement Analyser
    • Upload Statement
      POST
    • Statement Result
      GET
  • Account Aggregator
    • Initialize
      POST
    • Fetch JSON Report
      POST
    • Fetch PDF Report
      POST
    • Refresh Data
      POST
  • Multi Bureau
    • Multi-Bureau Fetch
      POST
  • Corporate
    • CIN Lookup
      POST
    • LLPIN
      POST
    • PAN Lookup
      POST
    • Company Autocomplete
      POST
  • EPFO
    • EPFO-CRIF Combined Report
      POST
  • ITR Analyzer
    • Initialize
      POST
    • Status
      GET
    • ITR Analyzer — Get Full Data
      GET
  • AA-BSA Analyzer
    • Initialize
      POST
    • Status
      GET
    • AA BSA — Statement Result
      GET
    • AA BSA — Analysis JSON
      GET
  1. Account Aggregator

Refresh Data

POST
/api/v1/services/account-aggregator/refresh-data

Account Aggregator - Refresh Data#

Endpoint Overview
POST api/v1/services/account-aggregator/refresh-data

Description#

The Account Aggregator V2 Refresh Data API enables developers to trigger a refresh of financial data from connected accounts through the Account Aggregator framework. This endpoint initiates a data refresh process for a specific client, ensuring that the most up-to-date financial information is available for analysis and processing. The API is designed to work within the Account Aggregator ecosystem, providing seamless integration for fintech applications requiring real-time financial data updates.
Key Benefits
Real-time Data Updates: Ensures financial data is current and accurate for decision-making
Seamless Integration: Works within the established Account Aggregator framework
Asynchronous Processing: Returns a request ID for tracking the refresh process
Reliable Performance: Built for high-volume financial data operations

Use Cases#

Fintech & Banking
Wealth Management
Insurance & Risk
Loan underwriting processes requiring the latest financial statements
Credit scoring updates when borrower financial status changes
Investment advisory services needing current portfolio data
Personal finance management apps syncing account balances

Technical Implementation#

1
Authentication
All API requests require authentication using API Key and API Secret headers. Authentication follows these steps:
1.
Obtain API Credentials: Register with Finpass to receive your x-api-key and x-api-secret.
2.
Include in Requests: Add both credentials as headers in every API request.
HeaderDescription
x-api-keyYour unique API key provided by Finpass upon registration.
x-api-secretYour API secret paired with the API key for authenticated access.
Production: https://api.finpass.ai
2
Request Parameters

Request Headers#

HeaderRequiredDescription
x-api-keyYesYour unique API key for authentication. Provided by Finpass during registration.
x-api-secretYesYour API secret paired with the API key. Provided by Finpass during registration.
Content-TypeYesMust be set to application/json

Request Body#

ParameterTypeRequiredDescription
client_idStringYesUnique identifier for the Account Aggregator V2 client session

Example Request#

{
  "client_id": "account_aggregator_v2_oOxRfypvwDqMjti"
}
3
Process Response

Response Parameters#

ParameterTypeDescription
dataObjectContains the response data with request tracking information
data.request_idStringUnique identifier for tracking the refresh data request
status_codeNumberHTTP status code indicating the result of the request
message_codeStringInternal status code for the operation
messageStringHuman-readable message describing the operation result
successBooleanIndicates whether the request was processed successfully

Example Successful Response#

{
  "data": {
    "request_id": "account_aggregator_v2_ojmzgkXAqwzTk"
  },
  "status_code": 200,
  "message_code": "success",
  "message": "Success",
  "success": true
}

Possible Error Responses#

Invalid Client ID
Authentication Error
{
  "data": null,
  "status_code": 400,
  "message_code": "invalid_client_id",
  "message": "Invalid or expired client ID provided",
  "success": false
}
Client ID is either malformed, expired, or doesn't exist in the system.

Integration Best Practices#

Security Recommendations
Secure Credential Storage: Store your x-api-key and x-api-secret securely using environment variables or a secrets manager (e.g., AWS Secrets Manager, HashiCorp Vault). Never hardcode credentials in source code or expose them in client-side applications.
HTTPS Only: Always use HTTPS for all API communications to protect sensitive financial data
Credential Rotation: Periodically rotate your API key and secret. Coordinate with Finpass support to regenerate credentials and update them across your deployments.
Rate Limiting: Implement request rate limiting to prevent API abuse
Audit Logging: Log all API interactions for audit and compliance purposes
User Experience Guidelines
Loading States: Implement proper loading states while data refresh is in progress
Status Feedback: Provide clear feedback to users about the refresh process status
Retry Logic: Handle network timeouts gracefully with appropriate retry mechanisms
Progress Tracking: Use the request_id to track and display refresh progress to end users

Code Samples#

cURL
Python
Node.js
Related APIs
Account Aggregator V2 Status Check: Monitor the progress of data refresh requests using the returned request_id
Account Aggregator Data Retrieval: Fetch the refreshed financial data once the refresh process is complete
Account Aggregator Session Management: Manage client sessions and connection status
Compliance and Legal Considerations
This API operates within the Account Aggregator framework governed by RBI guidelines. Ensure proper user consent is obtained before initiating data refresh operations. All data handling must comply with applicable data protection regulations including the Digital Personal Data Protection Act (DPDPA) and local privacy laws. Maintain audit trails for all data refresh activities for regulatory compliance.

Request

Header Params

Body Params application/jsonRequired

Examples

Responses

🟢200Success
application/json
Body

🟠422Account aggregator limit exceeded For this month
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request POST 'https://api.finpass.ai/api/v1/services/account-aggregator/refresh-data' \
--header 'X-API-Key: LG8zVXK1MZv1jP6i4l6QZQ2nD9kLTvFWipV_anPvacE' \
--header 'X-API-Secret: M5RwMtvbYGqAGZpG8d223xkEq1298kjcGGpJ7s7_' \
--header 'Content-Type: application/json' \
--data-raw '{
    "client_id": "aa_oOx8989898RfypvwDqMjti"
}'
Response Response Example
200 - Success
{
    "data": {
        "request_id": "account_aggregator_v2_oOxRfypvwDqMjti"
    },
    "status_code": 200,
    "message_code": "success",
    "message": "Success",
    "success": true
}
Previous
Fetch PDF Report
Next
Multi-Bureau Fetch
Built with