Fetch Account Aggregator - JSON Report

Endpoint Overview

POST /api/v1/account-aggregator-v2/fetch-json-report

Description

The Fetch Account Aggregator JSON Report API retrieves comprehensive financial data collected through the Account Aggregator framework in JSON format. This endpoint provides detailed bank account information including profile details, account summaries, and transaction histories for customers who have consented to share their financial data.

This API is designed to support various financial workflows including loan underwriting and loan monitoring. It returns structured data that includes customer profiles, account balances, transaction details, and other banking information collected through India's Account Aggregator ecosystem, enabling lenders and financial institutions to make informed credit decisions based on real-time financial data.

Key Benefits

Real-time Financial Data: Access up-to-date bank account information and transaction history with customer consent

Comprehensive Insights: Retrieve profile details, account summaries, and detailed transaction data in a single API call

Flexible Workflow Support: Works seamlessly with both loan underwriting and loan monitoring use cases

Structured Data Format: Returns well-organized JSON data that's easy to parse and integrate into existing systems

Use Cases

Lending & Credit

Financial Services

Risk Management

Loan Underwriting: Evaluate creditworthiness by analyzing real-time bank statements and transaction patterns before loan approval

Income Verification: Verify customer income through salary credits and regular deposit patterns for more accurate risk assessment

Cash Flow Analysis: Assess liquidity and financial stability by examining account balances and transaction frequencies

Technical Implementation

Authentication

All API requests require authentication using a JWT Bearer token. Authentication follows these steps:

Obtain API Credentials: Register with Surepass to receive your API key.

Generate JWT Token: Use your API key to generate a JWT token.

Include in Requests: Add the token to the Authorization header as Bearer TOKEN.

Different authentication tokens are used for sandbox and production environments:

Sandbox: https://sandbox.surepass.app

Production: https://kyc-api.surepass.app

Request Parameters

Request Headers

Header	Required	Description
Authorization	Yes	Bearer token for API authentication (Format: `Bearer YOUR_JWT_TOKEN`)
Content-Type	Yes	Must be set to `application/json`

Request Body

Parameter	Type	Required	Description
client_id	string	Yes	Unique identifier for the client in the Account Aggregator system. Format: `account_aggregator_v2_{random_string}`
request_id	string	Conditional	Unique identifier for the consent request obtained from the Refresh Data endpoint (`/api/v1/account-aggregator-v2/refresh-data`). Required for loan_monitoring flow. Optional for loan_underwriting flow.

Example Request

{
    "client_id": "account_aggregator_v2_oOxRfypvwDqMjtpqyi",
    "request_id": "account_aggregator_v2_ojmzgkXAqwzTroKzFBGk_hrBxcvsp"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object holding the account aggregator response data
data.client_id	string	Echo of the client_id from the request
data.account_aggregator_json	array	Array of account objects containing detailed financial information
data.account_aggregator_json[].account_id	string	Unique UUID identifier for the account
data.account_aggregator_json[].status	string	Status of the data fetch operation (e.g., "READY")
data.account_aggregator_json[].profile_details	object	Customer profile information
data.account_aggregator_json[].profile_details.name	string	Full name of the account holder
data.account_aggregator_json[].profile_details.dob	string	Date of birth in YYYY-MM-DD format
data.account_aggregator_json[].profile_details.mobile	string	Mobile number of the account holder
data.account_aggregator_json[].profile_details.nominee	string	Nominee name registered with the account
data.account_aggregator_json[].profile_details.landline	string	Landline number if available
data.account_aggregator_json[].profile_details.address	string	Complete address including PIN code
data.account_aggregator_json[].profile_details.email	string	Email address of the account holder
data.account_aggregator_json[].profile_details.pan	string	PAN (Permanent Account Number)
data.account_aggregator_json[].profile_details.ckyc_registered	string	Central KYC registration status ("true"/"false")
data.account_aggregator_json[].profile_details.type	string	Account holder type (e.g., "SINGLE", "JOINT")
data.account_aggregator_json[].summary_details	object	Account summary and balance information
data.account_aggregator_json[].summary_details.branch	string	Branch code
data.account_aggregator_json[].summary_details.facility	string	Credit facility status (e.g., "NO_FACILITY_GRANTED")
data.account_aggregator_json[].summary_details.micr_code	string	MICR code of the branch
data.account_aggregator_json[].summary_details.opening_date	string/null	Account opening date
data.account_aggregator_json[].summary_details.current_od_limit	string	Current overdraft limit amount
data.account_aggregator_json[].summary_details.drawing_limit	string	Drawing limit for the account
data.account_aggregator_json[].summary_details.status	string	Account status (e.g., "ACTIVE", "INACTIVE")
data.account_aggregator_json[].summary_details.account_type	string	Primary account type classification
data.account_aggregator_json[].summary_details.account_sub_type	string	Sub-type of account (e.g., "SAVINGS", "CURRENT")
data.account_aggregator_json[].summary_details.ifsc	string	IFSC code of the bank branch
data.account_aggregator_json[].summary_details.current_balance	string	Current account balance
data.account_aggregator_json[].summary_details.currency	string	Currency code (e.g., "INR")
data.account_aggregator_json[].summary_details.balance_date_time	string	Timestamp of balance update in ISO 8601 format
data.account_aggregator_json[].transaction_data	object	Container for transaction information
data.account_aggregator_json[].transaction_data.transaction_details	array	Array of individual transaction records
data.account_aggregator_json[].transaction_data.transaction_details[].transaction_id	string	Unique transaction identifier
data.account_aggregator_json[].transaction_data.transaction_details[].amount	number	Transaction amount
data.account_aggregator_json[].transaction_data.transaction_details[].narration	string	Transaction description/narration
data.account_aggregator_json[].transaction_data.transaction_details[].type	string	Transaction type ("DEBIT" or "CREDIT")
data.account_aggregator_json[].transaction_data.transaction_details[].mode	string	Transaction mode (e.g., "UPI", "NEFT", "IMPS")
data.account_aggregator_json[].transaction_data.transaction_details[].transaction_timestamp	string	Transaction timestamp in ISO 8601 format
data.account_aggregator_json[].transaction_data.transaction_details[].value_date	string	Value date of the transaction
data.account_aggregator_json[].transaction_data.transaction_details[].reference	string	Transaction reference number
data.account_aggregator_json[].transaction_data.transaction_details[].transactional_balance	string	Account balance after this transaction
data.account_aggregator_json[].transaction_data.start_date	string	Start date of transaction data period (YYYY-MM-DD)
data.account_aggregator_json[].transaction_data.end_date	string	End date of transaction data period (YYYY-MM-DD)
data.account_aggregator_json[].transaction_type	string	Type of account transactions (e.g., "deposit")
data.account_aggregator_json[].masked_account_number	string	Masked account number for security
status_code	integer	HTTP status code of the response
success	boolean	Indicates if the request was successful
message	string	Human-readable response message
message_code	string	Machine-readable message code

Example Successful Response

{
    "data": {
        "client_id": "account_aggregator_v2_oOxRfypvwDqMjtpqyi",
        "account_aggregator_json": [
            {
                "account_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
                "status": "READY",
                "profile_details": {
                    "name": "John Doe",
                    "dob": "1985-01-15",
                    "mobile": "9000000000",
                    "nominee": "Jane Doe",
                    "landline": "011-1234567",
                    "address": "123 Fake Street, Springfield, USA, PIN : 000000",
                    "email": "john.doe@example.com",
                    "pan": "ABCDE1234F",
                    "ckyc_registered": "true",
                    "type": "SINGLE"
                },
                "summary_details": {
                    "branch": "00001",
                    "facility": "NO_FACILITY_GRANTED",
                    "micr_code": "123456789",
                    "opening_date": null,
                    "current_od_limit": "0.00",
                    "drawing_limit": "50000.00",
                    "status": "ACTIVE",
                    "account_type": "",
                    "account_sub_type": "SAVINGS",
                    "ifsc": "FAKE0000001",
                    "current_balance": "98765.43",
                    "currency": "INR",
                    "balance_date_time": "2025-07-23T18:35:29+05:30"
                },
                "transaction_data": {
                    "transaction_details": [
                        {
                            "transaction_id": "T000001",
                            "amount": 1500,
                            "narration": "UPI/DR/Fake Payment 1",
                            "type": "DEBIT",
                            "mode": "UPI",
                            "transaction_timestamp": "2024-08-01T10:00:00+05:30",
                            "value_date": "2024-08-01T00:00:00+05:30",
                            "reference": "",
                            "transactional_balance": "97265.43"
                        },
                        {
                            "transaction_id": "T000002",
                            "amount": 2000,
                            "narration": "NEFT/CR/Fake Transfer 2",
                            "type": "CREDIT",
                            "mode": "NEFT",
                            "transaction_timestamp": "2024-08-02T11:15:00+05:30",
                            "value_date": "2024-08-02T00:00:00+05:30",
                            "reference": "",
                            "transactional_balance": "99265.43"
                        }
                    ],
                    "start_date": "2024-07-23",
                    "end_date": "2025-07-23"
                },
                "transaction_type": "deposit",
                "masked_account_number": "XXXXXXXXXXXXX1234"
            }
        ]
    },
    "status_code": 200,
    "success": true,
    "message": "Success",
    "message_code": "success"
}

Possible Error Responses

Authentication Error

Invalid Client ID

Missing Request ID

Data Not Ready

{
    "status_code": 401,
    "success": false,
    "message": "Unauthorized access. Invalid or expired token.",
    "message_code": "unauthorized"
}

This error occurs when the JWT Bearer token is missing, invalid, or expired. Ensure you're using a valid token in the Authorization header.

Integration Best Practices

Security Recommendations

Secure Token Storage: Store JWT tokens securely using environment variables or secure vault services, never hardcode them in your application

HTTPS Only: Always use HTTPS endpoints to ensure data transmission is encrypted

Data Minimization: Only request and store the financial data that is necessary for your specific use case

Access Controls: Implement role-based access controls to limit who can access sensitive financial data within your organization

Token Rotation: Regularly rotate your JWT tokens and implement token expiration handling in your application

Audit Logging: Maintain comprehensive logs of all API calls for compliance and security auditing purposes

User Experience Guidelines

Transparent Consent: Clearly communicate to users what financial data will be accessed and why before initiating the Account Aggregator flow

Progress Indicators: Display loading states when data is being fetched, as the process may take a few moments

Error Handling: Provide clear, user-friendly error messages when data fetch fails or authentication issues occur

Data Refresh Options: Allow users to refresh their data periodically for ongoing monitoring scenarios

Privacy Assurance: Inform users about data retention policies and how their financial information will be protected

Code Samples

cURL

Python

Node.js

Related APIs

Account Aggregator Initiation API: Use this API to initiate the Account Aggregator consent flow and generate client_id and request_id values that will be used with this fetch API.

Transaction Analytics API: Analyze the fetched transaction data to generate insights such as income patterns, spending behavior, and financial health scores.

Bank Statement Parser API: Alternative method for extracting financial data from uploaded bank statement PDFs when Account Aggregator integration is not available.

Compliance and Legal Considerations

Account Aggregator Framework Compliance: This API operates within India's Account Aggregator framework regulated by the Reserve Bank of India (RBI). Ensure your implementation complies with all RBI guidelines for data handling and customer consent.

Customer Consent: Always obtain explicit customer consent before accessing their financial data through the Account Aggregator network. Consent must be informed, specific, and revocable.

Data Retention: Follow data minimization principles and retain financial data only for the duration necessary to fulfill the stated purpose. Implement secure data deletion processes.

Privacy Regulations: Comply with applicable data protection regulations including the Digital Personal Data Protection Act (DPDPA) when handling customer financial information.

Purpose Limitation: Use the fetched financial data only for the specific purpose disclosed to and consented by the customer (e.g., loan underwriting or monitoring).

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Responses

🟢200Success

application/json

Body

🟢202Accepted

🟠404Client Not Found

🟠422Consent Status Pending

🟠422Consent Status Rejected

🟠422Consent Status Revoked

🟠422Consent Status Paused

🟠422Consent Status Expired

🟠422Account Aggregator Data Not Found

🟠422Account Fetch Failed

🟠422Account Data Fetch Error

🟠422Account Data Fetch Expired

🟠422Account Data Not Found

🟠422No Financial Information Request Found

🔴500Server Error

curl --location --request POST 'https://kyc-api.surepass.app/api/v1/account-aggregator-v2/fetch-json-report' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "client_id": "account_aggregator_v2_oOxRfypvwDqMjti" }'

{ "data": { "client_id": "account_aggregator_v2_oOxRfypvwDqMjti", "account_aggregator_json": [ { "account_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "status": "READY", "profile_details": { "name": "John Doe", "dob": "1985-01-15", "mobile": "9000000000", "nominee": "Jane Doe", "landline": "011-1234567", "address": "123 Fake Street, Springfield, USA, PIN : 000000", "email": "john.doe@example.com", "pan": "ABCDE1234F", "ckyc_registered": "true", "type": "SINGLE" }, "summary_details": { "branch": "00001", "facility": "NO_FACILITY_GRANTED", "micr_code": "123456789", "opening_date": null, "current_od_limit": "0.00", "drawing_limit": "50000.00", "status": "ACTIVE", "account_type": "", "account_sub_type": "SAVINGS", "ifsc": "FAKE0000001", "current_balance": "98765.43", "currency": "INR", "balance_date_time": "2025-07-23T18:35:29+05:30" }, "transaction_data": { "transaction_details": [ { "transaction_id": "T000001", "amount": 1500, "narration": "UPI/DR/Fake Payment 1", "type": "DEBIT", "mode": "UPI", "transaction_timestamp": "2024-08-01T10:00:00+05:30", "value_date": "2024-08-01T00:00:00+05:30", "reference": "", "transactional_balance": "97265.43" }, { "transaction_id": "T000002", "amount": 2000, "narration": "NEFT/CR/Fake Transfer 2", "type": "CREDIT", "mode": "NEFT", "transaction_timestamp": "2024-08-02T11:15:00+05:30", "value_date": "2024-08-02T00:00:00+05:30", "reference": "", "transactional_balance": "99265.43" }, { "transaction_id": "T000001", "amount": 1500, "narration": "UPI/DR/Fake Payment 1", "type": "DEBIT", "mode": "UPI", "transaction_timestamp": "2024-08-01T10:00:00+05:30", "value_date": "2025-08-10T00:00:00+05:30", "reference": "", "transactional_balance": "97265.43" }, { "transaction_id": "T000001", "amount": 1500, "narration": "UPI/DR/Fake Payment 1", "type": "DEBIT", "mode": "UPI", "transaction_timestamp": "2024-08-01T10:00:00+05:30", "value_date": "2025-08-11T00:00:00+05:30", "reference": "", "transactional_balance": "97265.43" }, { "transaction_id": "T000001", "amount": 1500, "narration": "UPI/DR/Fake Payment 1", "type": "CREDIT", "mode": "UPI", "transaction_timestamp": "2024-08-01T10:00:00+05:30", "value_date": "2024-08-01T00:00:00+05:30", "reference": "", "transactional_balance": "97265.43" }, { "transaction_id": "T000001", "amount": 1500, "narration": "UPI/DR/Fake Payment 1", "type": "CREDIT", "mode": "UPI", "transaction_timestamp": "2024-08-01T10:00:00+05:30", "value_date": "2024-08-01T00:00:00+05:30", "reference": "", "transactional_balance": "97265.43" } ], "start_date": "2024-07-23", "end_date": "2025-07-23" }, "transaction_type": "deposit", "masked_account_number": "XXXXXXXXXXXXX1234" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Fetch JSON Report

Fetch Account Aggregator - JSON Report#

Description#

Use Cases#

Technical Implementation#

Request Headers#

Request Body#

Example Request#

Response Parameters#

Example Successful Response#

Possible Error Responses#

Integration Best Practices#

Code Samples#

Request