Data Events

Overview

Data events notify your application about the status of financial data fetch operations. These events fire after an FI Request is submitted and the Account Aggregator processes the data retrieval. Data events use eventType: "DATA" (or "DATA_EXT" for DATA_PUSH) and include linkRefNumbers arrays with per-account fetch status.

Data Fetch Flow

linkRefNumbers Structure

Data events include a linkRefNumbers array with per-account status details. In Type 1 (basic) payloads, only linkRefNumber and fiStatus are included. Type 2 (extended) payloads add FIP details.

Field	Type	Present In	Description
`linkRefNumber`	string	Type 1 & 2	Unique reference for the linked account
`fiStatus`	string	Type 1 & 2	Account-level status: `READY`, `DENIED`, or `TIMEOUT`
`fipName`	string	Type 2 only	Display name of the Financial Information Provider
`fipId`	string	Type 2 only	Identifier of the FIP
`maskedAccountNumber`	string	Type 2 only	Masked account number (e.g., `XXXXXXXX7300`)

Events

DATA_READY

Sent when financial data has been successfully fetched and is ready for retrieval. Call the Get FI Data or Get All FI Data API to retrieve the data.

Basic Payload (Type 1)

{
  "timestamp": "2022-03-08T12:22:03.146Z",
  "consentHandle": "c7f0d368-a05f-468d-8d6c-c75acc17f224",
  "eventType": "DATA",
  "eventStatus": "DATA_READY",
  "consentId": "bf0cda0b-776c-4104-a4f8-5bcd69764125",
  "vua": "9999999999@onemoney",
  "eventMessage": "Data ready for consent id bf0cda0b-776c-4104-a4f8-5bcd69764125",
  "linkRefNumbers": [
    {
      "linkRefNumber": "e7597a05-5b56-4223-95fc3f-9596ff12eb",
      "fiStatus": "READY"
    }
  ]
}

Extended Payload (Type 2)

{
  "timestamp": "2023-03-10T06:26:10.823Z",
  "consentHandle": "5eada97a-9852-4227-9558-45849b2800a3",
  "eventType": "DATA",
  "eventStatus": "DATA_READY",
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435",
  "vua": "XXXXXXX773@onemoney",
  "eventMessage": "Data ready for consent id 3c92001e-57ea-4320-bbb8-66d524bfb435",
  "productID": "AGENT",
  "accountID": "AGENT1678429501561",
  "fetchType": "ONETIME",
  "consentExpiry": "2023-03-11 06:25:13",
  "dataExpiry": "2023-04-10T06:26:10.000Z",
  "firstTimeFetch": true,
  "linkRefNumbers": [
    {
      "linkRefNumber": "70814726-f02e-4db4-b380-df8d28ec6772",
      "fiStatus": "READY",
      "fipName": "FinShareBankServer",
      "fipId": "finsharebank",
      "maskedAccountNumber": "XXXXXXXX7300"
    }
  ]
}

On receiving DATA_READY, call Get FI Data or Get All FI Data to retrieve the financial information. The linkRefNumbers array tells you which accounts have data available.

DATA_DENIED

Sent when the FIP denies the data fetch request. This can happen when the FIP is unable or unwilling to share the requested data.

Basic Payload (Type 1)

{
  "timestamp": "2022-04-07T06:33:28.592Z",
  "consentHandle": "91c1cc00-e98b-4ee1-8b69-5afbae03f6b3",
  "eventType": "DATA",
  "eventStatus": "DATA_DENIED",
  "consentId": "2f93c7f3-5fc5-479c-bea2-dfdac731b159",
  "vua": "9999999999@onemoney",
  "eventMessage": "Data denied for consent id 2f93c7f3-5fc5-479c-bea2-dfdac731b159",
  "linkRefNumbers": [
    {
      "linkRefNumber": "efc18641-62c1-4706-a84c-dd86ea87f528",
      "fiStatus": "DENIED"
    }
  ]
}

Extended Payload (Type 2)

{
  "timestamp": "2023-02-23T12:26:28.548Z",
  "consentHandle": "60ff809a-61b6-4959-bb4a-81cb44ac1f51",
  "eventType": "DATA",
  "eventStatus": "DATA_DENIED",
  "consentId": "d2277986-a5cc-42c2-89cd-b8f4018dc309",
  "vua": "XXXXXXX773@onemoney",
  "eventMessage": "Data denied for consent id d2277986-a5cc-42c2-89cd-b8f4018dc309",
  "productID": "TESTONFEB17",
  "accountID": "1234",
  "fetchType": "PERIODIC",
  "consentExpiry": "2023-02-25 12:14:41",
  "dataExpiry": "",
  "linkRefNumbers": [
    {
      "linkRefNumber": "65a13110-d1db-4703-960b-39f7e02e7b23",
      "fiStatus": "DENIED",
      "fipName": "FinShareBankServer",
      "fipId": "finsharebank",
      "maskedAccountNumber": "XXXXXXXX7300"
    }
  ]
}

SESSION_FAILED

Sent when a data fetch session fails, typically due to a timeout at the FIP. The linkRefNumbers array shows TIMEOUT status for the affected accounts. Type 2 payloads include a sessionId for debugging.

Basic Payload (Type 1)

{
  "timestamp": "2022-04-07T07:28:37.485Z",
  "consentHandle": "995bad77-a003-402e-9b0d-8602c4069ef7",
  "eventType": "DATA",
  "eventStatus": "SESSION_FAILED",
  "consentId": "48ecb1ed-3256-463f-b9a9-7936a1bb6f79",
  "vua": "9999999999@onemoney",
  "eventMessage": "Data fetch failed for consent id 48ecb1ed-3256-463f-b9a9-7936a1bb6f79",
  "linkRefNumbers": [
    {
      "linkRefNumber": "5845ad3b-ae9d-435b-99fb-cc7462300706",
      "fiStatus": "TIMEOUT"
    }
  ]
}

Extended Payload (Type 2)

{
  "timestamp": "2023-09-28T06:38:37.886Z",
  "consentHandle": "f18714e0-001b-44ac-8c85-c3162c434516",
  "eventType": "DATA",
  "eventStatus": "SESSION_FAILED",
  "consentId": "59994ced-2620-4b12-9bd8-35025588887c",
  "vua": "9999999999@onemoney",
  "eventMessage": "Data fetch failed for consent id 59994ced-2620-4b12-9bd8-35025588887c",
  "productID": "TESTP",
  "accountID": "TESTP1695813566525",
  "fetchType": "PERIODIC",
  "consentExpiry": "2024-09-27 11:19:34",
  "dataExpiry": "2023-09-28T11:22:12.000Z",
  "sessionId": "728714aa-4fe3-430a-bd26-796ceea3de7d",
  "linkRefNumbers": [
    {
      "linkRefNumber": "cfe39ed2-0b92-4720-98a7-ffe03e3fbc13",
      "fiStatus": "TIMEOUT",
      "fipName": "FinShareBankServer",
      "fipId": "finsharebank",
      "maskedAccountNumber": "XXXXXXXX0600"
    }
  ]
}

Session failures are often transient. You can check the FI Request Status or submit a new FI Request to retry the data fetch.

SESSION_EXPIRED

Sent when a data fetch session expires before the FIP responds. Unlike SESSION_FAILED, this indicates the session’s time-to-live was exceeded rather than an explicit failure.

Basic Payload (Type 1)

{
  "timestamp": "2021-04-23T13:08:01.514Z",
  "consentHandle": "825da2f2-ae80-469b-b69b-6fb428107500",
  "eventType": "DATA",
  "eventStatus": "SESSION_EXPIRED",
  "consentId": "91a2bb4c-8197-42c5-8de3-4ba02c16196d",
  "vua": "9999999999@onemoney",
  "eventMessage": "Data fetch expired for consent id 91a2bb4c-8197-42c5-8de3-4ba02c16196d"
}

SESSION_EXPIRED events may not include linkRefNumbers. Submit a new FI Request to retry the data fetch if the consent is still active.

DATA_PUSH

Sent when FinPro pushes raw financial data directly in the webhook payload. This is an extended event (eventType: "DATA_EXT") that eliminates the need to call the Get FI Data API — the complete financial information is included inline in the data array.

Payload

{
  "timestamp": "2022-04-07T06:10:17.129Z",
  "consentHandle": "7793263e-ab71-4343-8f31-e7e695f4a3d1",
  "eventType": "DATA_EXT",
  "eventStatus": "DATA_PUSH",
  "consentId": "bd740c63-70a3-415a-944f-fc6b16e2c55f",
  "vua": "7730808773@onemoney",
  "eventMessage": "Data push for consent id bd740c63-70a3-415a-944f-fc6b16e2c55f",
  "productID": "AGENT",
  "accountID": "AGENT1678429501561",
  "fetchType": "ONETIME",
  "consentExpiry": "2023-03-11 06:25:13",
  "dataExpiry": "2023-04-10T06:26:10.000Z",
  "firstTimeFetch": true,
  "linkRefNumbers": [
    {
      "linkRefNumber": "70814726-f02e-4db4-b380-df8d28ec6772",
      "fiStatus": "READY",
      "fipName": "FinShareBankServer",
      "fipId": "finsharebank",
      "maskedAccountNumber": "XXXXXXXX7300"
    }
  ],
  "data": [
    {
      "linkReferenceNumber": "b520384b-7174-4951-98cf-b09574266e61",
      "maskedAccountNumber": "XXXXXX8773",
      "fiType": "RECURRING_DEPOSIT",
      "bank": "FinShareBankServer",
      "Summary": {
        "branch": "JayaNagar 4th Block",
        "openingDate": null,
        "ifsc": "ICIC0001124",
        "accountType": "RECURRING",
        "maturityAmount": "61693.00",
        "maturityDate": null,
        "description": "12 Months Recurring Deposit",
        "interestPayout": "OnMaturity",
        "interestRate": "5.15",
        "principalAmount": "5000.00",
        "tenureDays": "0",
        "tenureMonths": "12",
        "tenureYears": "0",
        "recurringAmount": "5000.00",
        "recurringDepositDay": "22",
        "interestComputation": "COMPOUND",
        "compoundingFrequency": "MONTHLY",
        "interestPeriodicPayoutAmount": "0",
        "interestOnMaturity": "1693",
        "currentValue": "35000.00"
      },
      "Profile": {
        "Holders": {
          "type": "SINGLE",
          "Holder": [
            {
              "name": "Akshay Kumar",
              "dob": "1947-08-15",
              "mobile": "7730808773",
              "nominee": "REGISTERED",
              "landline": "",
              "address": "8/1190, 5th Cross, 3rd Main, 7th Block, Jayanagar, Bangalore - 560011",
              "email": "mail@mail.com",
              "pan": "AAAAA0000A",
              "ckycCompliance": "true"
            }
          ]
        }
      },
      "Transactions": {
        "startDate": "2019-04-07",
        "endDate": "2022-04-07",
        "Transaction": [
          {
            "type": "OPENING",
            "mode": "FT",
            "amount": "5000.00",
            "balance": "5000.00",
            "transactionDateTime": "2019-12-22T04:53:45.000Z",
            "valueDate": "2019-12-22T04:53:45.000Z",
            "txnId": "M2587459",
            "narration": "TOWARDS RD OPENING",
            "reference": "RFN0001338754"
          }
        ]
      }
    }
  ]
}

data Array Structure

Each entry in the data array represents one financial account:

Field	Type	Description
`linkReferenceNumber`	string	Unique reference for the linked account
`maskedAccountNumber`	string	Masked account number
`fiType`	string	Financial information type (e.g., `DEPOSIT`, `MUTUAL_FUNDS`, `EQUITIES`, `RECURRING_DEPOSIT`, `TERM_DEPOSIT`, `ETF`)
`bank`	string	FIP/bank name
`Summary`	object	Account summary with type-specific fields (balance, maturity, interest, etc.)
`Profile`	object	Account holder profile information
`Transactions`	object	Transaction history within the requested date range

DATA_PUSH payloads can be large since they contain full financial data inline. Ensure your webhook endpoint can handle payloads up to several megabytes and process them asynchronously.

With DATA_PUSH, you do not need to call the Get FI Data or Get All FI Data APIs — the data is delivered directly in the webhook payload.

Integration Guidance

Event	Recommended Action
`DATA_READY`	Call Get FI Data or Get All FI Data to retrieve the financial data
`DATA_DENIED`	Log the denial; check FIP status via FIP Health; notify the user if needed
`SESSION_FAILED`	Retry with a new FI Request; check FIP Health if failures persist
`SESSION_EXPIRED`	Submit a new FI Request if the consent is still active
`DATA_PUSH`	Process the inline `data` array directly — no additional API calls needed

Getting Started

Platform Overview

Core Features

Webhooks

Overview

Data Fetch Flow

linkRefNumbers Structure

Events

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Payload

data Array Structure

Integration Guidance

​Overview

​Data Fetch Flow

​linkRefNumbers Structure

​Events

​Basic Payload (Type 1)

​Extended Payload (Type 2)

​Basic Payload (Type 1)

​Extended Payload (Type 2)

​Basic Payload (Type 1)

​Extended Payload (Type 2)

​Basic Payload (Type 1)

​Payload

​data Array Structure

​Integration Guidance

Overview

Data Fetch Flow

linkRefNumbers Structure

Events

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Extended Payload (Type 2)

Basic Payload (Type 1)

Payload

data Array Structure

Integration Guidance