User Nudges API

Overview

The User Nudges API provides personalized financial recommendations and prompts to help users make informed financial decisions. Nudges are intelligently evaluated based on user’s financial data, behavior patterns, and configured criteria to deliver contextually relevant suggestions at the right time. Financial nudges can include investment opportunities, savings recommendations, KYC completion reminders, spending insights, portfolio rebalancing suggestions, and other personalized financial guidance designed to improve user engagement and financial outcomes.

Example Request

This API is called in response to receiving a Nudges Callback Webhook notification, which indicates that new nudges have been evaluated and are ready for retrieval.

curl --location 'https://api-uat.pfm.equal.in/pfm/user/nudges' \
--header 'Content-Type: application/json' \
--header 'authorization: eyJh...'

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

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

import requests

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

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

Authentication

This API requires Bearer token authentication:

Header	Type	Required	Description
`authorization`	string	Yes	Bearer token obtained from the SDK Init API session
`Content-Type`	string	Yes	Must be set to `application/json`

Response

Success Response (200 OK)

When nudges are successfully evaluated, the API returns personalized recommendations:

{
  "status": "SUCCESS",
  "message": "Nudges evaluated successfully",
  "data": {
    "reference_id": "user-123",
    "evaluated_at": "2025-12-15T10:30:00.123Z",
    "eligible_nudges": [
      {
        "nudge_id": "nudge_4fc2d942-4523-44a5-b73f-1130d78f4284",
        "nudge_name": "High Salary Investment Offer",
        "message": "You qualify for our premium investment options!",
        "metadata": {}
      },
      {
        "nudge_id": "nudge_8ab3c123-5678-90de-f012-3456789abcde",
        "nudge_name": "Complete KYC Reminder",
        "message": "Complete your KYC to unlock all features!",
        "metadata": {}
      }
    ],
    "summary": {
      "total_configured": 8,
      "total_eligible": 2
    }
  }
}

Response Fields

Field	Type	Description
`status`	string	Status of the API call. Will be `SUCCESS` for successful requests.
`message`	string	Descriptive message about the nudge evaluation process.
`data`	object	Contains nudge evaluation results and user-specific recommendations.
`data.reference_id`	string	Unique identifier for the user provided by your application during onboarding.
`data.evaluated_at`	string	ISO timestamp when the nudges were evaluated.
`data.eligible_nudges`	array	Array of nudges that the user is eligible for based on their profile and financial data.
`data.summary`	object	Summary statistics about nudge evaluation.

Eligible Nudges Fields

Field	Type	Description
`nudge_id`	string	Unique identifier for the nudge configuration.
`nudge_name`	string	Client-defined name/title for the nudge.
`message`	string	Client-defined message content to display to the user.
`metadata`	object	Additional custom data associated with the nudge (currently empty, reserved for future use).

Summary Fields

Field	Type	Description
`total_configured`	number	Total number of nudges configured for the client.
`total_eligible`	number	Number of nudges the user is currently eligible for.

Nudge Configuration

Nudges are currently configured through our technical team based on your specific requirements:

Targeting Criteria: Income levels, investment amounts, account types, user behavior
Content Personalization: Custom messages and call-to-action text

Error Responses

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

Error Handling

Error Code	HTTP Status	Description	Resolution
`invalid_session_token`	401 Unauthorized	The provided authorization token is invalid, expired, or malformed	Obtain a new valid JWT token for API authentication

Implementation Guidelines

Real-time Evaluation: Call this API when users access your application for up-to-date nudges
Smart Display: Implement logic to show nudges at appropriate moments in your user journey
User Experience: Avoid overwhelming users with too many nudges simultaneously

Next Steps

To set up nudges for your application:

Define Use Cases: Identify specific nudge scenarios relevant to your users
Contact Technical Team: Reach out to configure your nudge criteria and content
Integration Testing: Implement the API and test with various user scenarios

PFM Overview

Architecture

Analytics Data Dictionary

Integration Guide

API Encryption Guide

PFM APIs

Scheduled Data Sharing

Overview

Example Request

Authentication

Response

Success Response (200 OK)

Response Fields

Eligible Nudges Fields

Summary Fields

Nudge Configuration

Error Responses

Error Handling

Implementation Guidelines

Next Steps

​Overview

​Example Request

​Authentication

​Response

​Success Response (200 OK)

​Response Fields

​Eligible Nudges Fields

​Summary Fields

​Nudge Configuration

​Error Responses

​Error Handling

​Implementation Guidelines

​Next Steps

Overview

Example Request

Authentication

Response

Success Response (200 OK)

Response Fields

Eligible Nudges Fields

Summary Fields

Nudge Configuration

Error Responses

Error Handling

Implementation Guidelines

Next Steps