Skip to main content
POST
/
api
/
v1
/
users
Create User
curl --request POST \
  --url https://api.example.com/api/v1/users \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "username": "<string>",
  "password": "<string>",
  "email": "<string>",
  "phone": "<string>",
  "role": "<string>",
  "ventanaId": "<string>",
  "code": "<string>",
  "isActive": true
}
'
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Juan Pérez",
    "username": "jperez",
    "email": "[email protected]",
    "phone": "8091234567",
    "role": "VENDEDOR",
    "ventanaId": "660e8400-e29b-41d4-a716-446655440000",
    "code": "V001",
    "isActive": true,
    "settings": null,
    "platform": null,
    "appVersion": null,
    "deletedAt": null,
    "deletedBy": null,
    "deletedReason": null,
    "createdAt": "2024-03-15T12:00:00Z",
    "updatedAt": "2024-03-15T12:00:00Z"
  }
}

​
Overview

Creates a new user with specified role (ADMIN, VENTANA, or VENDEDOR). VENTANA users can only create VENDEDOR users within their own ventana.

​
Authorization

Required role: ADMIN or VENTANA
Permissions:
  • ADMIN: Can create users with any role
  • VENTANA: Can only create VENDEDOR users within their ventana

​
Request Body

​
name
string
required
User’s full name (2-100 characters)
​
username
string
required
Unique username (3-32 characters)
​
password
string
required
Password (minimum 6 characters)
​
email
string
Email address (must be valid email format, unique)
​
phone
string
Phone number (max 32 characters, format: ###-####-####)
​
role
string
User role: “ADMIN”, “VENTANA”, or “VENDEDOR” (default: “VENTANA”)
​
ventanaId
string
UUID of associated ventana (required for VENTANA and VENDEDOR roles)
​
code
string
Unique user code (optional)
​
isActive
boolean
default:"true"
Whether the user is active

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
The created user object
{
  "success": true,
  "data": {
    "id": "770e8400-e29b-41d4-a716-446655440000",
    "name": "Juan Pérez",
    "username": "jperez",
    "email": "[email protected]",
    "phone": "8091234567",
    "role": "VENDEDOR",
    "ventanaId": "660e8400-e29b-41d4-a716-446655440000",
    "code": "V001",
    "isActive": true,
    "settings": null,
    "platform": null,
    "appVersion": null,
    "deletedAt": null,
    "deletedBy": null,
    "deletedReason": null,
    "createdAt": "2024-03-15T12:00:00Z",
    "updatedAt": "2024-03-15T12:00:00Z"
  }
}

​
Notes

  • Password is hashed before storage using bcrypt
  • Username is case-insensitive (stored as Citext in database)
  • Phone numbers are normalized to remove separators
  • Non-ADMIN roles require ventanaId (validation in src/api/v1/validators/user.validator.ts:71-83)
  • Activity log created with USER_CREATE event (see src/api/v1/controllers/user.controller.ts:30-38)
  • VENTANA users automatically filtered to their ventana (enforced by service layer)

Build docs developers (and LLMs) love

Get started for freeTalk to us