FIP Health

Overview

The FIP Health API fetches real-time health metrics for Financial Information Providers (FIPs) from multiple Account Aggregators and returns a unified, aggregated response. This API is essential for monitoring FIP performance, making informed AA routing decisions, and providing transparency to users about expected service quality.

Key Features

Multi-AA Aggregation: Collects health data from all enabled AAs in a single API call
Unified Response Format: Normalizes different AA response formats into a consistent structure
Three-Level Filtering: Filter by AA, FIP, and event type
Comprehensive Metrics: Includes latency percentiles, success rates, and error rates

Use Cases

Smart AA Routing: Choose the optimal AA based on FIP health metrics for specific operations
Service Monitoring: Track FIP availability and performance across different AAs
User Experience: Display expected wait times and success rates to users before consent/data fetch operations
Alerting: Set up alerts for FIP degradation or outages

Authentication

This API requires the following authentication headers with every request:

Header	Type	Required	Description
`client_id`	string	Yes	API key issued to your organisation for authentication
`client_secret`	string	Yes	Secret API key for secure server-side authentication
`organisationId`	string	Yes	Unique identifier assigned to your organisation
`appIdentifier`	string	Yes	Unique identifier for your client application
`Content-Type`	string	Yes	Must be set to `application/json`

Request Body

All request parameters are optional. An empty request body {} returns health data for all AAs, FIPs, and event types.

aaId

string[]

Optional array of AA identifiers to filter results to specific Account Aggregators.Format: Array of alphanumeric strings (without @ symbol)Example: ["onemoney", "anumati"]

fipIds

string[]

Optional array of FIP identifiers to filter results to specific Financial Information Providers.Format: Array of FIP ID stringsExample: ["HDFC-FIP", "ICICI-FIP"]

eventTypes

string[]

Optional array of event types to filter results to specific operations.Valid Values:

DISCOVERY - Account discovery operations
LINKING-INIT - Account linking initialization
LINKING-OTP - Account linking OTP verification
CONSENT - Consent creation/approval
FI-REQUEST - Financial Information request initiation
FI-FETCH - Financial Information data fetch
FI-NOTIFICATION - FI notification callbacks
DELINKING - Account delinking operations

Example: ["DISCOVERY", "CONSENT", "FI-FETCH"]

Response

Success Response

ver

string

API version number.Example: "1.0.0"

status

string

Request status.Value: "success"

timestamp

string

ISO 8601 timestamp of when the response was generated.Example: "2025-11-25T10:30:00.000Z"

data

array

Array of FIP health entries, grouped by FIP and event type.

data[].fipId

string

FIP identifier.Example: "HDFC-FIP"

data[].eventType

string

Type of operation this metric applies to.Example: "DISCOVERY"

data[].aaWiseMetrics

array

Array of metrics from each AA for this FIP and event type combination.

data[].aaWiseMetrics[].aaId

string

Account Aggregator identifier.Example: "onemoney"

data[].aaWiseMetrics[].refreshRateInSec

number

How frequently this AA refreshes its health metrics, in seconds.Example: 600 (10 minutes)

data[].aaWiseMetrics[].supported

boolean

Whether this AA supports interactions with this FIP.Example: true

data[].aaWiseMetrics[].latencyP50

number | null

50th percentile (median) latency in milliseconds.Example: 650

data[].aaWiseMetrics[].latencyP90

number | null

90th percentile latency in milliseconds.Example: 720

data[].aaWiseMetrics[].latencyP95

number | null

95th percentile latency in milliseconds.Example: 740

data[].aaWiseMetrics[].latencyP99

number | null

99th percentile latency in milliseconds.Example: 800

data[].aaWiseMetrics[].latencyAvg

number | null

Average latency in milliseconds.Example: 680

data[].aaWiseMetrics[].latencyMax

number | null

Maximum observed latency in milliseconds.Example: 900

data[].aaWiseMetrics[].successRate

number | null

Percentage of successful operations.Example: 98.5

data[].aaWiseMetrics[].timeoutRate

number | null

Percentage of operations that timed out.Example: 0.5

data[].aaWiseMetrics[].accNotFoundRate

number | null

Percentage of operations where account was not found.Example: 0.8

data[].aaWiseMetrics[].serverErrorRate

number | null

Percentage of operations that resulted in server errors.Example: 0.1

data[].aaWiseMetrics[].clientErrorRate

number | null

Percentage of operations that resulted in client errors.Example: 0.1

Example Requests

Get All Health Data

Retrieve health metrics for all AAs, FIPs, and event types:

{}

Filter by AA

Get health data only from specific Account Aggregators:

{
  "aaId": ["onemoney", "anumati"]
}

Filter by FIP

Get health data for specific Financial Information Providers:

{
  "fipIds": ["HDFC-FIP", "ICICI-FIP"]
}

Filter by Event Type

Get health data for specific operations:

{
  "eventTypes": ["DISCOVERY", "CONSENT"]
}

Combined Filters

Apply multiple filters together:

{
  "aaId": ["onemoney"],
  "fipIds": ["HDFC-FIP"],
  "eventTypes": ["DISCOVERY", "FI-REQUEST"]
}

Example Response

{
  "ver": "1.0.0",
  "status": "success",
  "timestamp": "2025-11-25T10:30:00.000Z",
  "data": [
    {
      "fipId": "HDFC-FIP",
      "eventType": "DISCOVERY",
      "aaWiseMetrics": [
        {
          "aaId": "onemoney",
          "refreshRateInSec": 600,
          "supported": true,
          "latencyP50": 650,
          "latencyP90": 720,
          "latencyP95": 740,
          "latencyP99": 800,
          "latencyAvg": 680,
          "latencyMax": 900,
          "successRate": 98.5,
          "timeoutRate": 0.5,
          "accNotFoundRate": 0.8,
          "serverErrorRate": 0.1,
          "clientErrorRate": 0.1
        },
        {
          "aaId": "finvu",
          "refreshRateInSec": 60,
          "supported": true,
          "latencyP50": 450,
          "latencyP90": 520,
          "latencyP95": 550,
          "latencyP99": 600,
          "latencyAvg": 480,
          "latencyMax": 750,
          "successRate": 99.2,
          "timeoutRate": 0.3,
          "accNotFoundRate": 0.4,
          "serverErrorRate": 0.05,
          "clientErrorRate": 0.05
        }
      ]
    },
    {
      "fipId": "HDFC-FIP",
      "eventType": "FI-FETCH",
      "aaWiseMetrics": [
        {
          "aaId": "onemoney",
          "refreshRateInSec": 600,
          "supported": true,
          "latencyP50": 2500,
          "latencyP90": 3200,
          "latencyP95": 3800,
          "latencyP99": 4500,
          "latencyAvg": 2800,
          "latencyMax": 5000,
          "successRate": 95.0,
          "timeoutRate": 2.0,
          "accNotFoundRate": 1.5,
          "serverErrorRate": 1.0,
          "clientErrorRate": 0.5
        }
      ]
    }
  ]
}

Event Types Explained

Event Type	Description	Typical Use
`DISCOVERY`	Account discovery - finding user accounts at a FIP	Initial consent flow, showing available accounts
`LINKING-INIT`	Starting the account linking process	One-time account setup
`LINKING-OTP`	OTP verification during account linking	Account verification
`CONSENT`	Consent creation and approval	Core consent workflow
`FI-REQUEST`	Initiating a financial information request	Data pull initiation
`FI-FETCH`	Fetching the actual financial data	Data retrieval
`FI-NOTIFICATION`	Receiving notifications from FIP	Async data availability
`DELINKING`	Removing linked accounts	Account management

Use Cases

Smart AA Routing

Select the best AA based on health metrics for a specific FIP:

async function selectBestAA(fipId, eventType) {
  const response = await getFipHealth({
    fipIds: [fipId],
    eventTypes: [eventType]
  });

  const fipData = response.data.find(d =>
    d.fipId === fipId && d.eventType === eventType
  );

  if (!fipData || fipData.aaWiseMetrics.length === 0) {
    return null; // No data available
  }

  // Find AA with highest success rate among supported ones
  const bestAA = fipData.aaWiseMetrics
    .filter(m => m.supported && m.successRate !== null)
    .sort((a, b) => b.successRate - a.successRate)[0];

  return bestAA?.aaId;
}

Performance Monitoring Dashboard

Display FIP health status for monitoring:

function categorizeFipHealth(metrics) {
  if (!metrics.supported) return 'unsupported';
  if (metrics.successRate >= 98) return 'healthy';
  if (metrics.successRate >= 90) return 'degraded';
  return 'critical';
}

async function buildHealthDashboard() {
  const response = await getFipHealth({});

  const dashboard = response.data.map(entry => ({
    fipId: entry.fipId,
    eventType: entry.eventType,
    aaStatus: entry.aaWiseMetrics.map(m => ({
      aaId: m.aaId,
      status: categorizeFipHealth(m),
      successRate: m.successRate,
      avgLatency: m.latencyAvg
    }))
  }));

  return dashboard;
}

User Experience Enhancement

Show expected wait times before operations:

async function getExpectedLatency(fipId, aaId, eventType) {
  const response = await getFipHealth({
    fipIds: [fipId],
    aaId: [aaId],
    eventTypes: [eventType]
  });

  const metrics = response.data[0]?.aaWiseMetrics[0];

  if (!metrics) {
    return { available: false };
  }

  return {
    available: true,
    expectedLatencyMs: metrics.latencyP90, // Use P90 for conservative estimate
    successRate: metrics.successRate,
    lastUpdated: response.timestamp
  };
}

// Display to user
const latencyInfo = await getExpectedLatency('HDFC-FIP', 'onemoney', 'FI-FETCH');
if (latencyInfo.available) {
  console.log(`Expected wait time: ~${Math.ceil(latencyInfo.expectedLatencyMs / 1000)} seconds`);
  console.log(`Success rate: ${latencyInfo.successRate}%`);
}

Usage Notes

Understanding Metrics

Latency Percentiles: P50 represents median experience, P99 represents worst-case experience for 1% of requests
Success Rate: Percentage of requests that completed successfully (not timed out, not errored)
Null Values: Metrics may be null if insufficient data is available from an AA

Refresh Rates

Different AAs update their health metrics at different intervals:

AA	Typical Refresh Rate
OneMoney	10 minutes (600s)
Finvu	1 minute (60s)
Anumati	10 minutes (600s)

The refreshRateInSec field indicates how frequently data is updated for each AA.

Filtering Behavior

aaId filter: Applied during AA request phase - only queries specified AAs
fipIds filter: Applied post-aggregation - filters merged results by FIP
eventTypes filter: Applied post-aggregation - filters merged results by event type

Note: Some AAs may return data for all FIPs regardless of filters. FinPro applies additional filtering to ensure consistent results.

Best Practices

Cache Results: Health metrics don’t change rapidly. Cache results based on the smallest refreshRateInSec value in the response
Use Appropriate Percentiles: Use P50 for typical experience, P90/P95 for SLA monitoring, P99 for worst-case planning
Monitor Trends: Compare current metrics with historical values to detect degradation
Handle Missing Data: Always check for null values before using metrics in calculations
Combine with Profile Check: Use FIP Health data together with Profile Check to make optimal AA routing decisions

Rate Limiting

This API is subject to rate limiting:

Metric	Value
Limit	1000 requests per time window
Remaining	Returned in `X-RateLimit-Remaining` header
Reset	Returned in `X-RateLimit-Reset` header

Given the caching potential of this API, you should rarely need to call it more than once per minute.

AA List - Get the list of integrated Account Aggregators
FIP List - Get the list of Financial Information Providers
Check Profile - Check user registration status across AAs
Consent Request V4 - Create consent requests with optimal AA selection

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

Overview

Key Features

Use Cases

Authentication

Request Body

Response

Success Response

Example Requests

Get All Health Data

Filter by AA

Filter by FIP

Filter by Event Type

Combined Filters

Example Response

Event Types Explained

Use Cases

Smart AA Routing

Performance Monitoring Dashboard

User Experience Enhancement

Usage Notes

Understanding Metrics

Refresh Rates

Filtering Behavior

Best Practices

Rate Limiting

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

​Overview

​Key Features

​Use Cases

​Authentication

​Request Body

​Response

​Success Response

​Example Requests

​Get All Health Data

​Filter by AA

​Filter by FIP

​Filter by Event Type

​Combined Filters

​Example Response

​Event Types Explained

​Use Cases

​Smart AA Routing

​Performance Monitoring Dashboard

​User Experience Enhancement

​Usage Notes

​Understanding Metrics

​Refresh Rates

​Filtering Behavior

​Best Practices

​Rate Limiting

​Related APIs

Overview

Key Features

Use Cases

Authentication

Request Body

Response

Success Response

Example Requests

Get All Health Data

Filter by AA

Filter by FIP

Filter by Event Type

Combined Filters

Example Response

Event Types Explained

Use Cases

Smart AA Routing

Performance Monitoring Dashboard

User Experience Enhancement

Usage Notes

Understanding Metrics

Refresh Rates

Filtering Behavior

Best Practices

Rate Limiting

Related APIs