Skip to main content

​
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..'

​
Authentication

This API requires Bearer token authentication using a JWT token:
HeaderTypeRequiredDescription
authorizationstringYesJWT Bearer token for API authentication
Content-TypestringYesMust be set to application/json

​
Query Parameters

ParameterTypeRequiredDescription
idstringYesData 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"
  ]
}
FieldTypeDescription
statusstringStatus of the API call. Will be SUCCESS for successful requests.
transaction_idstringUnique identifier for the transaction/request.
data_statusstringCurrent status of user’s data. See Data Status Values below.
dataobject(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_typesarray(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

StatusDescription
NO_CONSENTS_RAISEDUser is new and no consents have been raised yet. User needs to start the consent process.
NO_APPROVED_CONSENTSConsents exist but are either revoked, rejected, or expired. User needs to provide new consents.
DATA_AVAILABLEData 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"
}
FieldTypeDescription
statusstringStatus of the API call. Will be FAILED for failed requests.
messagestringHuman-readable error message explaining what went wrong.
status_codestringMachine-readable error code for programmatic error handling.
transaction_idstring(Optional) Unique identifier for the transaction when available.

​
Error Handling

Error CodeHTTP StatusDescriptionResolution
invalid_data_id400 Bad RequestThe provided data config ID is invalid or not configuredProvide a valid data config ID that has been set up for your client
invalid_session_token401 UnauthorizedThe provided authorization token is invalid, expired, or malformedObtain a new valid JWT token for API authentication

​
Usage Flow

  1. Check Data Status: Call this API to understand the current state of user’s data
  2. 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)
  3. 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.