Skip to main content

​
Endpoint

POST /api/v1/users

​
Description

Creates a new user account in the system with notification preferences. The user can be configured to receive email and/or push notifications.

​
Authentication

This endpoint may require authentication depending on your system configuration.

​
Request Body

​
name
string
required
The full name of the user.Example: John DoeValidation: Must be a non-empty string
​
email
string (email)
required
The email address of the user.Example: [email protected]Validation: Must be a valid email address format
​
push_token
string
Firebase Cloud Messaging (FCM) token for push notifications.Example: fcm_token_string_exampleNote: Optional - provide this if the user wants to receive push notifications
​
preferences
object
User notification preferences.Example: {"email": true, "push": false}
​
password
string
required
User password for authentication.Note: This field is required for user account creation. Ensure proper password hashing is implemented server-side.

​
Response

​
user_id
string (UUID)
Unique identifier assigned to the newly created userExample: 123e4567-e89b-12d3-a456-426614174000
​
name
string
Full name of the userExample: John Doe
​
email
string
Email address of the userExample: [email protected]
​
push_token
string | null
Firebase Cloud Messaging tokenExample: fcm_token_string_example
​
preferences
object
User notification preferencesExample: {"email": true, "push": false}
​
created_at
string (ISO 8601)
Timestamp when the user was createdExample: 2024-03-15T10:30:00.000Z

​
Error Responses

​
400 Bad Request
error
Returned when the request payload is invalid.Example scenarios:
  • Invalid email format
  • Missing required fields
  • Email already exists
{
  "statusCode": 400,
  "message": [
    "email must be an email",
    "name should not be empty"
  ],
  "error": "Bad Request"
}
​
409 Conflict
error
Returned when a user with the specified email already exists.
{
  "statusCode": 409,
  "message": "User with email [email protected] already exists",
  "error": "Conflict"
}

​
Example Request

curl -X POST http://localhost:8001/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "[email protected]",
    "push_token": "fcm_token_abc123xyz789",
    "preferences": {
      "email": true,
      "push": false
    },
    "password": "securePassword123"
  }'

​
Example Response

201 Created
{
  "user_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "email": "[email protected]",
  "push_token": "fcm_token_abc123xyz789",
  "preferences": {
    "email": true,
    "push": false
  },
  "created_at": "2024-03-15T10:30:00.000Z"
}

​
Notes

  • User preferences are stored in PostgreSQL and cached in Redis for quick access
  • The push_token is required if the user wants to receive push notifications
  • Email uniqueness is enforced at the database level
  • Passwords are hashed before storage (never stored in plain text)
  • After creation, the user can receive notifications based on their preferences
  • The User Service validates all fields using NestJS validation pipes

Build docs developers (and LLMs) love

Get started for freeTalk to us