Skip to main content

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

​
Authentication

This API requires Bearer token authentication:
HeaderTypeRequiredDescription
authorizationstringYesBearer token obtained from the SDK Init API session
Content-TypestringYesMust 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

FieldTypeDescription
statusstringStatus of the API call. Will be SUCCESS for successful requests.
messagestringDescriptive message about the nudge evaluation process.
dataobjectContains nudge evaluation results and user-specific recommendations.
data.reference_idstringUnique identifier for the user provided by your application during onboarding.
data.evaluated_atstringISO timestamp when the nudges were evaluated.
data.eligible_nudgesarrayArray of nudges that the user is eligible for based on their profile and financial data.
data.summaryobjectSummary statistics about nudge evaluation.

​
Eligible Nudges Fields

FieldTypeDescription
nudge_idstringUnique identifier for the nudge configuration.
nudge_namestringClient-defined name/title for the nudge.
messagestringClient-defined message content to display to the user.
metadataobjectAdditional custom data associated with the nudge (currently empty, reserved for future use).

​
Summary Fields

FieldTypeDescription
total_configurednumberTotal number of nudges configured for the client.
total_eligiblenumberNumber 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 CodeHTTP StatusDescriptionResolution
invalid_session_token401 UnauthorizedThe provided authorization token is invalid, expired, or malformedObtain 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:
  1. Define Use Cases: Identify specific nudge scenarios relevant to your users
  2. Contact Technical Team: Reach out to configure your nudge criteria and content
  3. Integration Testing: Implement the API and test with various user scenarios