Account Aggregator V2 - Fetch Statement PDF

Endpoint Overview

POST /api/v1/account-aggregator-v2/fetch-statement-pdf

Description

The Fetch Statement PDF API enables you to retrieve consolidated bank statement reports in PDF format for accounts linked through the Account Aggregator framework. This endpoint provides download links to statement reports for multiple Financial Information Providers (FIPs) associated with a given client and request.

This API is designed to work seamlessly within loan underwriting and loan monitoring workflows, providing instant access to formatted financial statements that can be used for credit assessment, compliance documentation, and financial analysis.

Key Benefits

Multi-FIP Consolidation: Retrieve statement PDFs from multiple banks and financial institutions in a single API call

Workflow Flexibility: Supports both loan underwriting (requires request_id) and loan monitoring (optional request_id) use cases

Pre-signed URLs: Returns secure, time-limited download links for immediate PDF access

Status Transparency: Clear status indicators for each account's report availability

Use Cases

Lending & Credit

Fintech & Banking

Wealth & Advisory

Loan Underwriting: Retrieve comprehensive bank statements during loan application processing to assess creditworthiness and repayment capacity

Credit Risk Assessment: Generate PDF reports for manual review by credit officers and risk teams

Document Collection: Compile statement PDFs as part of mandatory loan documentation requirements

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 <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/customer in the Account Aggregator system. Format: `account_aggregator_v2_{unique_id}`
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_oOxRfypvwDqMjti",
  "request_id": "account_aggregator_v2_ojmzgkXAqwzTroKp"
}

Process Response

Response Parameters

Parameter	Type	Description
data	object	Container object for the response data
data.client_id	string	Echo of the client_id from the request
data.reports	array	Array of report objects, one for each FIP/account combination
data.reports[].fip_id	string	Financial Information Provider identifier (e.g., "HDFC-FIP", "SBI-FIP")
data.reports[].account_number	string	Masked account number for privacy (e.g., "XXXXXXXXXX1234")
data.reports[].status	string	Report generation status. Values: "READY", "PENDING", "FAILED"
data.reports[].statement_report_link	string	Pre-signed URL to download the PDF report. Valid for limited time
status_code	integer	HTTP status code (200 for success)
success	boolean	Indicates whether the request was successful
message	string	Human-readable response message
message_code	string	Machine-readable message code for programmatic handling

Example Successful Response

{
  "data": {
    "client_id": "account_aggregator_v2_oOxRfypvwDqMjti",
    "reports": [
      {
        "fip_id": "HDFC-FIP",
        "account_number": "XXXXXXXXXX1234",
        "status": "READY",
        "statement_report_link": "https://example.com/dummy-report-1.pdf?dummy_signature=1234567890abcdef"
      },
      {
        "fip_id": "SBI-FIP",
        "account_number": "XXXXXXXX9876",
        "status": "READY",
        "statement_report_link": "https://example.com/dummy-report-2.pdf?dummy_signature=abcdef1234567890"
      }
    ]
  },
  "status_code": 200,
  "success": true,
  "message": "Success",
  "message_code": "success"
}

Possible Error Responses

Invalid Client ID

Missing Request ID

Unauthorized

Reports Not Ready

{
  "data": null,
  "status_code": 404,
  "success": false,
  "message": "Client not found",
  "message_code": "client_not_found"
}

This error occurs when the provided client_id does not exist in the system or is incorrectly formatted.

Integration Best Practices

Security Recommendations

Token Security: Store JWT tokens securely and never expose them in client-side code or version control

HTTPS Only: Always use HTTPS for API calls to ensure data encryption in transit

URL Expiration: Download PDFs promptly as pre-signed URLs are time-limited (typically 15-60 minutes)

Access Control: Implement proper authorization checks to ensure users only access their own statements

Data Retention: Delete downloaded PDFs securely after processing and follow data retention policies

User Experience Guidelines

Status Polling: If reports show "PENDING" status, implement polling with exponential backoff (start at 5 seconds, max 30 seconds)

Progress Indicators: Show users clear loading states when fetching statements from multiple FIPs

Error Handling: Provide user-friendly error messages when reports are unavailable or failed

Download Management: Allow users to download individual FIP statements or all statements as a batch

Timeout Handling: Set appropriate timeouts (30-60 seconds) and inform users if the operation takes longer than expected

Code Samples

cURL

Python

Node.js

Related APIs

Refresh Data (/api/v1/account-aggregator-v2/refresh-data): Trigger data refresh and obtain the request_id required for loan_underwriting flow

Initiate Consent Request: Start the Account Aggregator consent flow to link customer accounts

Fetch Account Data: Retrieve raw transaction data in JSON format instead of PDF reports

Check Consent Status: Verify the status of pending consent requests

Revoke Consent: Allow customers to revoke previously granted data access permissions

Compliance and Legal Considerations

This API operates within the Reserve Bank of India's Account Aggregator framework and must comply with:

RBI Account Aggregator Guidelines: All data access must be consent-based and purpose-limited

Data Protection: Customer financial data must be handled in accordance with applicable data protection laws

Consent Validity: Ensure consents are valid and not expired before fetching statements

Purpose Limitation: Use fetched data only for the stated purpose (loan underwriting/monitoring)

Audit Trail: Maintain logs of all API calls for regulatory compliance and dispute resolution

Customer Rights: Honor customer requests for data deletion and consent withdrawal promptly

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

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

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

{ "data": { "client_id": "account_aggregator_v2_oOxRfypvwDqMjti", "reports": [ { "fip_id": "HDFC-FIP", "account_number": "XXXXXXXXXX1234", "status": "READY", "statement_report_link": "https://example.com/dummy-report-1.pdf?dummy_signature=1234567890abcdef" }, { "fip_id": "SBI-FIP", "account_number": "XXXXXXXX9876", "status": "READY", "statement_report_link": "https://example.com/dummy-report-2.pdf?dummy_signature=abcdef1234567890" } ] }, "status_code": 200, "success": true, "message": "Success", "message_code": "success" }

Fetch Statement PDF

Account Aggregator V2 - Fetch Statement PDF#

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

Responses