> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.

# User Nudges API

> Retrieve personalized financial nudges and recommendations for users

## 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](/pfm/webhooks#available-webhooks) notification, which indicates that new nudges have been evaluated and are ready for retrieval.

<CodeGroup>
  ```bash cURL theme={null}
  curl --location 'https://api-uat.pfm.equal.in/pfm/user/nudges' \
  --header 'Content-Type: application/json' \
  --header 'authorization: eyJh...'
  ```

  ```javascript JavaScript theme={null}
  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);
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

## 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:

```json theme={null}
{
  "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

<CodeGroup>
  ```json Invalid Session Token theme={null}
  {
    "status": "FAILED",
    "message": "INVALID SESSION TOKEN",
    "status_code": "invalid_session_token"
  }
  ```
</CodeGroup>

## 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:

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