Skip to main content

​
Endpoint

PUT /api/v1/users/{id}/preferences
Updates only the notification preferences for a user without modifying other user information. This is a dedicated endpoint for managing notification channel preferences.

​
Path parameters

​
id
string
required
The unique identifier (UUID) of the user

​
Request body

​
preferences
object
required
Notification preferences object. Only include the channels you want to update - partial updates are supported.

​
Response

Returns the updated user object with new preferences applied.
​
id
string
User’s unique identifier
​
name
string
User’s name (unchanged)
​
email
string
User’s email (unchanged)
​
push_token
string
User’s push token (unchanged)
​
preferences
object
Updated notification preferences
​
updated_at
string
ISO 8601 timestamp of the update

​
Example request

cURL
curl -X PUT http://localhost:8001/api/v1/users/123e4567-e89b-12d3-a456-426614174000/preferences \
  -H "Content-Type: application/json" \
  -d '{
    "preferences": {
      "email": false,
      "push": true
    }
  }'
JavaScript
const userId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `http://localhost:8001/api/v1/users/${userId}/preferences`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      preferences: {
        email: false,
        push: true
      }
    })
  }
);

const updatedUser = await response.json();
Python
import requests

user_id = '123e4567-e89b-12d3-a456-426614174000'

response = requests.put(
    f'http://localhost:8001/api/v1/users/{user_id}/preferences',
    json={
        'preferences': {
            'email': False,
            'push': True
        }
    }
)

updated_user = response.json()

​
Example response

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "email": "[email protected]",
  "push_token": "fcm_token_abc123",
  "preferences": {
    "email": false,
    "push": true
  },
  "created_at": "2024-03-01T10:00:00Z",
  "updated_at": "2024-03-03T18:20:00Z"
}

​
Error responses

​
404 Not Found
error
User with the specified ID does not exist
{
  "statusCode": 404,
  "message": "User not found"
}
​
400 Bad Request
error
Invalid preferences object or missing required field
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["preferences must be an object"]
}

​
Use cases

  • User preferences page in application settings
  • Opt-in/opt-out flows for notification channels
  • GDPR compliance - allow users to control communication preferences
  • Notification preferences widget

​
Integration with notification flow

When a notification is queued, the Email Service and Push Service check user preferences before sending:
  1. API Gateway queues notification to RabbitMQ
  2. Worker service (Email/Push) fetches user data
  3. Worker checks preferences - if channel is disabled, notification is skipped
  4. If enabled, notification is sent
Preferences are cached in Redis by the notification workers for fast lookups. Updates to preferences may take a few seconds to propagate to the cache.
Disabling all notification channels means the user will not receive any notifications. Consider keeping at least one channel enabled or implementing a warning in your UI.

Build docs developers (and LLMs) love

Get started for freeTalk to us