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

# Notifications API

> Manage user notifications and preferences

# Notifications API

Endpoints for managing notifications and user preferences.

## Get Notifications

Retrieve user notifications.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/notifications?limit=20" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": "notif_1",
        "type": "loan_due_reminder",
        "title": "Loan Payment Due Tomorrow",
        "body": "Your loan #123 is due tomorrow. Total: $51.35",
        "read": false,
        "data": {
          "loanId": "loan_123",
          "amount": 51.35,
          "dueDate": "2024-01-16T12:00:00Z"
        },
        "createdAt": "2024-01-15T09:00:00Z"
      },
      {
        "id": "notif_2",
        "type": "guardian_request",
        "title": "Guardian Request",
        "body": "Bob wants you to be their guardian",
        "read": true,
        "data": {
          "requesterId": "user_bob",
          "requesterName": "Bob"
        },
        "createdAt": "2024-01-14T15:00:00Z"
      }
    ],
    "pagination": {
      "total": 45,
      "limit": 20,
      "offset": 0,
      "hasMore": true
    },
    "unreadCount": 3
  }
  ```
</CodeGroup>

### Query Parameters

| Parameter | Type    | Description                    |
| --------- | ------- | ------------------------------ |
| `limit`   | number  | Results per page (default: 20) |
| `offset`  | number  | Pagination offset              |
| `unread`  | boolean | Filter unread only             |
| `type`    | string  | Filter by notification type    |

## Get Unread Count

Get count of unread notifications.

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/notifications/unread/count" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "unreadCount": 3
    }
  }
  ```
</CodeGroup>

## Mark as Read

Mark notifications as read.

### Single Notification

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH "https://api.usmewe.com/v1/notifications/{notifId}/read" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "id": "notif_1",
      "read": true
    }
  }
  ```
</CodeGroup>

### Mark All Read

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/notifications/read-all" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "markedRead": 3
    }
  }
  ```
</CodeGroup>

## Delete Notification

Delete a notification.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "https://api.usmewe.com/v1/notifications/{notifId}" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Notification deleted"
  }
  ```
</CodeGroup>

## Notification Types

| Type                         | Description                     |
| ---------------------------- | ------------------------------- |
| `loan_created`               | Loan request created            |
| `loan_funded`                | Loan has been funded            |
| `loan_due_reminder`          | Payment due reminder            |
| `loan_overdue`               | Loan is overdue                 |
| `loan_repaid`                | Loan successfully repaid        |
| `guardian_request`           | Guardian invitation received    |
| `guardian_accepted`          | Guardian accepted invitation    |
| `withdrawal_requested`       | Social Vault withdrawal pending |
| `withdrawal_approval_needed` | Guardian approval needed        |
| `vault_locked`               | Social Vault locked (duress)    |
| `trust_score_updated`        | Trust Score changed             |
| `level_up`                   | User leveled up                 |
| `badge_earned`               | New badge earned                |

## Notification Preferences

### Get Preferences

<CodeGroup>
  ```bash Request theme={null}
  curl -X GET "https://api.usmewe.com/v1/notifications/preferences" \
    -H "Authorization: Bearer YOUR_TOKEN"
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "push": {
        "enabled": true,
        "loan_reminders": true,
        "guardian_alerts": true,
        "marketing": false
      },
      "email": {
        "enabled": true,
        "loan_reminders": true,
        "guardian_alerts": true,
        "weekly_summary": true,
        "marketing": false
      },
      "sms": {
        "enabled": false
      }
    }
  }
  ```
</CodeGroup>

### Update Preferences

<CodeGroup>
  ```bash Request theme={null}
  curl -X PATCH "https://api.usmewe.com/v1/notifications/preferences" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "push": {
        "marketing": false
      },
      "email": {
        "weekly_summary": false
      }
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "push": {
        "enabled": true,
        "loan_reminders": true,
        "guardian_alerts": true,
        "marketing": false
      },
      "email": {
        "enabled": true,
        "loan_reminders": true,
        "guardian_alerts": true,
        "weekly_summary": false,
        "marketing": false
      }
    }
  }
  ```
</CodeGroup>

## Register Push Token

Register device for push notifications.

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/notifications/push/register" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "token": "ExponentPushToken[xxx]",
      "platform": "ios",
      "deviceId": "device_abc123"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "registered": true,
      "deviceId": "device_abc123"
    }
  }
  ```
</CodeGroup>

## Unregister Push Token

Remove device from push notifications.

<CodeGroup>
  ```bash Request theme={null}
  curl -X DELETE "https://api.usmewe.com/v1/notifications/push/unregister" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "deviceId": "device_abc123"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Device unregistered"
  }
  ```
</CodeGroup>

## Test Notification

Send a test notification (development only).

<CodeGroup>
  ```bash Request theme={null}
  curl -X POST "https://api.usmewe.com/v1/notifications/test" \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "push"
    }'
  ```

  ```json Response theme={null}
  {
    "success": true,
    "message": "Test notification sent"
  }
  ```
</CodeGroup>

## Error Responses

| Code | Error                    | Description                |
| ---- | ------------------------ | -------------------------- |
| 404  | `NOTIFICATION_NOT_FOUND` | Notification doesn't exist |
| 400  | `INVALID_TOKEN`          | Invalid push token format  |
| 429  | `RATE_LIMITED`           | Too many requests          |