Skip to main content

​
Endpoint

DELETE /api/v1/users/{id}
Permanently deletes a user from the notification system. This action cannot be undone.
This is a destructive operation. The user record and all associated data will be permanently removed from the database.

​
Path parameters

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

​
Response

Returns HTTP 204 No Content on successful deletion with no response body.

​
Example request

cURL
curl -X DELETE http://localhost:8001/api/v1/users/123e4567-e89b-12d3-a456-426614174000
JavaScript
const userId = '123e4567-e89b-12d3-a456-426614174000';

const response = await fetch(
  `http://localhost:8001/api/v1/users/${userId}`,
  {
    method: 'DELETE'
  }
);

// Response status: 204 No Content
console.log(response.status); // 204
Python
import requests

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

response = requests.delete(
    f'http://localhost:8001/api/v1/users/{user_id}'
)

# Response status: 204 No Content
print(response.status_code)  # 204

​
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 user ID format (not a valid UUID)
{
  "statusCode": 400,
  "message": "Validation failed",
  "errors": ["id must be a valid UUID"]
}

​
Use cases

  • User account deletion (GDPR “right to be forgotten”)
  • Administrative cleanup of test accounts
  • Account deactivation workflow
  • User-initiated account removal

​
Considerations

​
Data implications

When a user is deleted:
  • User record is removed from PostgreSQL database
  • Associated preferences are deleted
  • Push tokens are removed

​
Pending notifications

Deleting a user does not affect notifications already queued in RabbitMQ. If a notification for this user is being processed, the worker services will fail to find the user and log an error. The notification will be moved to the failed queue.

​
Best practices

  1. Warn users before deletion - Implement a confirmation dialog in your application
  2. Consider soft delete - Instead of permanent deletion, add a deleted_at timestamp and filter deleted users from queries
  3. Archive data - Export user data before deletion for compliance or backup purposes
  4. Cascade cleanup - Ensure related records in other systems are also cleaned up

​
Alternative: Soft delete pattern

For production systems, consider implementing soft delete instead of hard delete: 
// Add to User entity
@Column({ type: 'timestamp', nullable: true })
deleted_at?: Date;

// Modify delete method
async softDelete(id: string): Promise<void> {
  await this.userRepository.update(id, { 
    deleted_at: new Date() 
  });
}

// Filter deleted users in queries
async findAll(): Promise<User[]> {
  return this.userRepository.find({
    where: { deleted_at: null }
  });
}
This approach allows you to:
  • Recover accidentally deleted accounts
  • Maintain referential integrity
  • Comply with data retention policies
  • Audit deletion history

Build docs developers (and LLMs) love

Get started for freeTalk to us