User Data API

{
  "status": "SUCCESS",
  "data": {}, // custom data output - can be partial or complete
  "transaction_id": "7179021e-0b7e-4983-93d0-fbee6013c866",
  "data_status": "DATA_AVAILABLE",
  "consented_fi_types": [
    "DEPOSIT",
    "EQUITIES",
    "ETF",
    "MUTUAL_FUNDS"
  ]
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_CONSENTS_RAISED"
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_APPROVED_CONSENTS"
}

{
  "status": "SUCCESS",
  "data": {}, // custom data output - can be partial or complete
  "transaction_id": "7179021e-0b7e-4983-93d0-fbee6013c866",
  "data_status": "DATA_AVAILABLE",
  "consented_fi_types": [
    "DEPOSIT",
    "EQUITIES",
    "ETF",
    "MUTUAL_FUNDS"
  ]
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_CONSENTS_RAISED"
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_APPROVED_CONSENTS"
}

Overview

The User Data API provides information about the status of a user’s PFM data and retrieves the actual data when available. This API uses configurable data structures defined by data config IDs, allowing clients to receive data in their preferred custom format. It tracks the complete data lifecycle from consent management to data availability.

Example Request

curl --location 'https://api-uat.pfm.equal.in/pfm/user/data?id=DEFAULT' \
--header 'Content-Type: application/json' \
--header 'authorization: eyJhb..'

const response = await fetch('https://api-uat.pfm.equal.in/pfm/user/data?id=DEFAULT', {
  method: 'GET',
  headers: {
    'Content-Type': 'application/json',
    'authorization': 'eyJhb..'
  }
});

const data = await response.json();
console.log('User Data Response:', data);

import requests

url = "https://api-uat.pfm.equal.in/pfm/user/data"
headers = {
    "Content-Type": "application/json",
    "authorization": "eyJhb.."
}

params = {
    "id": "DEFAULT"
}

response = requests.get(url, headers=headers, params=params)
print(response.json())

Authentication

This API requires Bearer token authentication using a JWT token:

Header	Type	Required	Description
`authorization`	string	Yes	JWT Bearer token for API authentication
`Content-Type`	string	Yes	Must be set to `application/json`

Query Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Data config ID that defines the custom structure/format of the data required by the client. Use `DEFAULT` for testing purposes.

Response

Success Response (200 OK)

The API returns different responses based on the current status of the user’s data:

{
  "status": "SUCCESS",
  "data": {}, // custom data output - can be partial or complete
  "transaction_id": "7179021e-0b7e-4983-93d0-fbee6013c866",
  "data_status": "DATA_AVAILABLE",
  "consented_fi_types": [
    "DEPOSIT",
    "EQUITIES",
    "ETF",
    "MUTUAL_FUNDS"
  ]
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_CONSENTS_RAISED"
}

{
  "status": "SUCCESS",
  "transaction_id": "2096e20a-38ec-458a-8452-c9c0c412d310",
  "data_status": "NO_APPROVED_CONSENTS"
}

Field	Type	Description
`status`	string	Status of the API call. Will be `SUCCESS` for successful requests.
`transaction_id`	string	Unique identifier for the transaction/request.
`data_status`	string	Current status of user’s data. See Data Status Values below.
`data`	object	(Optional) User’s financial data in the configured custom format. Can be partial data (basic account information) or complete data (full financial details). Only present when `data_status` is `DATA_AVAILABLE`.
`consented_fi_types`	array	(Optional) Array of FI types for which user has provided consent. Only present when `data_status` is `DATA_AVAILABLE`. Possible values: `DEPOSIT`, `MUTUAL_FUNDS`, `EQUITIES`, `TERM_DEPOSIT`, `RECURRING_DEPOSIT`, `ETF`.

Data Status Values

Status	Description
`NO_CONSENTS_RAISED`	User is new and no consents have been raised yet. User needs to start the consent process.
`NO_APPROVED_CONSENTS`	Consents exist but are either revoked, rejected, or expired. User needs to provide new consents.
`DATA_AVAILABLE`	Data is available for the user. This can be partial data (basic information about accounts for which user gave consent) or complete data (after user data is fully fetched). The response includes the `data` field with user’s financial information.

Sample Data Field Response

When entire data is available, the data field contains comprehensive financial information structured as follows:

{
  "data": {
    "bankAccounts": {
      "overallBankAccountsAnalytics": {
        "netBankBalance": 94629.77,
        "monthlyData": [
          {
            "date": "12-12-2025",
            "amount": 94386.15
          },
          {
            "date": "30-11-2025",
            "amount": 94386.15
          }
        ]
      },
      "bankAccountSummaryList": [
        {
          "bankName": "FinShareBankServer",
          "accountNumber": "XXXXXXXXX2041",
          "totalCreditAmount": 1829.51,
          "totalDebitAmount": 10644.44,
          "averageEODBalance": 3370.78,
          "currentBalance": 1912.86,
          "lastUpdatedTimestamp": "12-12-2025",
          "linkRefNo": "0e500b71-a958-4053-93cb-37f98880ea2b",
          "partialData": false
        }
      ],
      "analyticsVersion": "1.0.0"
    },
    "mutualFunds": {
      "overallMutualFundsAnalytics": {
        "netMutualFundsAmount": 1824071.82,
        "xirr": 0.0,
        "ofUsXirr": 0.0,
        "monthlyData": [
          {
            "date": "12-2025",
            "amount": 1824071.82
          }
        ]
      },
      "amcMutualFundsDetailsList": [
        {
          "folioNo": "8619809232072",
          "amcName" : "",
          "lastUpdatedTimestamp": "12-12-2025",
          "linkRefNo": "180b60b3-4d2f-4ad2-9902-56b6e16b7636",
          "mutualFunds": [
            {
              "nav": 423.596,
              "mutualFundName": "",
              "units": 459.725,
              "currentValue": 194737.67,
              "xirr": 0.0,
              "schemeType": "Equity(G)"
            }
          ],
          "partialData": false
        }
      ],
      "analyticsVersion": "1.0.0"
    },
    "equities": {
      "overallEquitiesAnalytics": {
        "netEquitiesAmount": 2759681.5,
        "monthlyData": [
          {
            "date": "12-2025",
            "amount": 2759681.5
          }
        ]
      },
      "equitySummaryList": [
        {
          "name": "",
          "unitsHeld": 300.0,
          "lastTradedPrice": 109.38,
          "currentValue": 32814.0,
          "depository": "FinShareBankServer",
          "lastUpdatedTimestamp": "12-12-2025",
          "linkRefNo": "ba7ba42b-283b-4036-91f0-0f9f5d2ba255",
          "xirr": 0.0,
          "partialData": false
        }
      ],
      "analyticsVersion": "1.0.0"
    },
    "etfs": {
      "overallEtfAnalytics": {
        "netEtfAmount": 0.0,
        "monthlyData": [
          {
            "date": "12-2025",
            "amount": 0.0
          }
        ]
      },
      "etfSummaryList": [
        {
          "isin": "IN000AAA000A",
          "name": "ABC BANK LIMITED EQ LISTING",
          "unitsHeld": 50.0,
          "lastNavPrice": 0.0,
          "currentValue": 0.0,
          "folioNo": "XXXXX4567",
          "lastUpdatedTimestamp": "12-12-2025",
          "linkRefNo": "4d3d13a9-67ad-47c0-af81-7062071283ca",
          "xirr": 0.0,
          "schemeType": "",
          "partialData": false
        }
      ],
      "analyticsVersion": "1.0.0"
    },
    "recurringDeposits": {
      "overallRecurringDepositsAnalytics": {
        "netRecurringDepositsBalance": 416276.83,
        "monthlyData": [
          {
            "date": "12-2025",
            "amount": 0.0
          }
        ]
      },
      "recurringDepositSummaryList": [
        {
          "currentValue": "416276.83",
          "principalAmount": "6000.00",
          "interestOnMaturity": "5.05",
          "interestRate": "5.05",
          "tenure": "4 years, 8 months, 5 days",
          "openingDate": "06-11-2020",
          "closingDate": "11-07-2025",
          "bankName": "FinShareBankServer",
          "lastUpdatedTimestamp": "12-12-2025",
          "linkRefNo": "41112ef1-9e71-4c6e-91c3-ee28ee5a78cf",
          "partialData": false
        }
      ],
      "analyticsVersion": "1.0.0"
    },
    "combinedFIAnalytics": {
      "name": "Equal Test",
      "age": 26,
      "netWorth": 5094659.92,
      "averageMonthlyInvestment": 0.0,
      "averageMonthlyExpense": 1876.49,
      "analyticsGenerationDate": "19-12-2025"
    },
    "fiTypes": [
      "DEPOSIT",
      "EQUITIES",
      "ETF",
      "RECURRING_DEPOSIT",
      "MUTUAL_FUNDS"
    ]
  }
}

Error Responses (400 Bad Request / 401 Unauthorized)

When the request fails, the API returns specific error responses:

{
  "status": "FAILED",
  "message": "Invalid Data ID",
  "status_code": "invalid_data_id",
  "transaction_id": "5b62604d-4e58-4d2f-84b4-a5ab1fd5c130"
}

{
  "status": "FAILED",
  "message": "INVALID SESSION TOKEN",
  "status_code": "invalid_session_token"
}

Field	Type	Description
`status`	string	Status of the API call. Will be `FAILED` for failed requests.
`message`	string	Human-readable error message explaining what went wrong.
`status_code`	string	Machine-readable error code for programmatic error handling.
`transaction_id`	string	(Optional) Unique identifier for the transaction when available.

Error Handling

Error Code	HTTP Status	Description	Resolution
`invalid_data_id`	400 Bad Request	The provided data config ID is invalid or not configured	Provide a valid data config ID that has been set up for your client
`invalid_session_token`	401 Unauthorized	The provided authorization token is invalid, expired, or malformed	Obtain a new valid JWT token for API authentication

Usage Flow

Check Data Status: Call this API to understand the current state of user’s data
Handle Different Statuses:
- NO_CONSENTS_RAISED: Direct user to onboarding flow
- NO_APPROVED_CONSENTS: Guide user to raise new consents via the onboarding flow
- DATA_AVAILABLE: Process and display the user’s financial data (can be partial or complete)
Data Processing: When data is available, use the custom-formatted data for your application needs

Data Configuration

The id parameter refers to a data config ID that defines:

Custom Data Structure: The specific format and fields required by your application
Data Scope: Which financial information types to include (deposits, investments, etc.)
Response Format: How the data should be organized and presented
Field Mapping: Custom field names and data transformations

For testing purposes, use id=DEFAULT which provides a standard data structure.

Security Considerations

Token Security: Handle JWT tokens securely and avoid logging them
Data Privacy: Ensure proper handling of sensitive financial data returned in responses
Encryption Support: This API supports encryption. When encryption is enabled for your integration, both request and response payloads will be encrypted. See API Encryption Guide for details.

PFM Overview

Architecture

Analytics Data Dictionary

Integration Guide

API Encryption Guide

PFM APIs

Scheduled Data Sharing

Overview

Example Request

Authentication

Query Parameters

Response

Success Response (200 OK)

Data Status Values

Sample Data Field Response

Error Responses (400 Bad Request / 401 Unauthorized)

Error Handling

Usage Flow

Data Configuration

Security Considerations

​Overview

​Example Request

​Authentication

​Query Parameters

​Response

​Success Response (200 OK)

​Data Status Values

​Sample Data Field Response

​Error Responses (400 Bad Request / 401 Unauthorized)

​Error Handling

​Usage Flow

​Data Configuration

​Security Considerations

Overview

Example Request

Authentication

Query Parameters

Response

Success Response (200 OK)

Data Status Values

Sample Data Field Response

Error Responses (400 Bad Request / 401 Unauthorized)

Error Handling

Usage Flow

Data Configuration

Security Considerations