Skip to main content
POST
/
api
/
users
Create User
curl --request POST \
  --url https://api.example.com/api/users \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "name": "<string>",
  "surname": "<string>",
  "password": "<string>",
  "role": {},
  "status": {},
  "phone": "<string>",
  "address": "<string>",
  "city": "<string>",
  "country": "<string>",
  "postal_code": "<string>",
  "gender": "<string>",
  "birth_date": "<string>",
  "document_type": {},
  "document_number": "<string>",
  "avatar": "<string>"
}
'
{
  "user_id": "<string>",
  "email": "<string>",
  "name": "<string>",
  "surname": "<string>",
  "phone": "<string>",
  "address": "<string>",
  "city": "<string>",
  "country": "<string>",
  "postal_code": "<string>",
  "gender": "<string>",
  "birth_date": "<string>",
  "role": {},
  "status": {},
  "avatar": "<string>",
  "document_type": {},
  "document_number": "<string>",
  "refresh_token": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}
Creates a new user account with the provided information. This endpoint is protected and requires authentication.

​
Authentication

This endpoint requires a valid JWT token. Include the token in one of the following ways:
  • Authorization header: Authorization: Bearer <token>
  • Cookie: auth_token=<token>

​
Authorization

Typically requires ADMIN role to create users, though this depends on your implementation of role-based access control.

​
Request Body

​
email
string
required
User’s email address (max 50 characters). Must be unique in the system.
​
name
string
required
User’s first name (max 50 characters)
​
surname
string
User’s last name (max 50 characters). Defaults to empty string if not provided.
​
password
string
User’s password. Will be hashed using bcrypt with 10 salt rounds. Defaults to "123456" if not provided.
The password is hashed using bcryptjs before storage. Never store plain-text passwords.
​
role
enum
default:"USER"
User’s role in the systemPossible values:
  • ADMIN: Administrator with full access
  • USER: Regular user with limited access
​
status
enum
default:"ON"
User’s account statusPossible values:
  • ON: Active account
  • OFF: Inactive/disabled account
​
phone
string
User’s phone number (max 20 characters). Defaults to empty string.
​
address
string
Street address (max 255 characters). Defaults to empty string.
​
city
string
City name (max 50 characters). Defaults to empty string.
​
country
string
Country name (max 50 characters). Defaults to empty string.
​
postal_code
string
Postal/ZIP code (max 20 characters). Defaults to empty string.
​
gender
string
User’s gender (max 10 characters). Defaults to empty string.
​
birth_date
string
Date of birth in ISO 8601 format (YYYY-MM-DD). Defaults to "1990-01-01" if not provided.
​
document_type
enum
default:"DNI"
Type of identification documentPossible values:
  • DNI: National Identity Document (Spain)
  • PASSPORT: Passport
  • NIE: Foreign Identity Number (Spain)
​
document_number
string
Document identification number (max 20 characters). Defaults to empty string.
​
avatar
string
URL to user’s avatar image (max 255 characters). If not provided, generates a default avatar using ui-avatars.com based on the user’s name.

​
Example Request

curl -X POST https://your-domain.com/api/users \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Laura",
    "surname": "Martínez",
    "email": "[email protected]",
    "password": "SecurePass123!",
    "role": "USER",
    "phone": "+34655443322",
    "address": "Calle de la Rosa 78",
    "city": "Valencia",
    "country": "España",
    "postal_code": "46001",
    "gender": "Femenino",
    "birth_date": "1995-08-22",
    "document_type": "DNI",
    "document_number": "23456789C"
  }'

​
Response

Returns the created user object without the password field.
​
user_id
string
Unique identifier for the user (UUID format, max 100 characters)
​
email
string
User’s email address
​
name
string
User’s first name
​
surname
string
User’s last name
​
phone
string
User’s phone number
​
address
string
Street address
​
city
string
City name
​
country
string
Country name
​
postal_code
string
Postal/ZIP code
​
gender
string
User’s gender
​
birth_date
string
Date of birth in ISO 8601 format
​
role
enum
User’s role (ADMIN or USER)
​
status
enum
User’s account status (ON or OFF)
​
avatar
string
URL to user’s avatar image
​
document_type
enum
Type of identification document
​
document_number
string
Document identification number
​
refresh_token
string | null
JWT refresh token (null for newly created users)
​
created_at
string
Timestamp when the user was created
​
updated_at
string
Timestamp when the user was last updated

​
Success Response (200)

{
  "user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "email": "[email protected]",
  "name": "Laura",
  "surname": "Martínez",
  "phone": "+34655443322",
  "address": "Calle de la Rosa 78",
  "city": "Valencia",
  "country": "España",
  "postal_code": "46001",
  "gender": "Femenino",
  "birth_date": "1995-08-22T00:00:00.000Z",
  "role": "USER",
  "status": "ON",
  "avatar": "https://ui-avatars.com/api/?name=Laura&background=random",
  "document_type": "DNI",
  "document_number": "23456789C",
  "refresh_token": null,
  "created_at": "2024-03-05T10:30:00.000Z",
  "updated_at": "2024-03-05T10:30:00.000Z"
}

​
Error Responses

​
400 Bad Request - Missing Fields
Required fields (email and name) are missing
{
  "statusCode": 400,
  "statusMessage": "Faltan campos obligatorios"
}
​
400 Bad Request - Duplicate Email
Email address is already registered
{
  "statusCode": 400,
  "statusMessage": "El email ya está en uso"
}
​
401 Unauthorized
Token is missing, invalid, or expired
{
  "statusCode": 401,
  "statusMessage": "Unauthorized: Token is missing or invalid"
}
​
500 Internal Server Error
Database error or server issue
{
  "statusCode": 500,
  "statusMessage": "Error al crear usuario"
}

​
Implementation Details

​
Password Hashing

Passwords are hashed using bcryptjs with 10 salt rounds before storage: 
const hashedPassword = await bcrypt.hash(password || '123456', 10)
Never store plain-text passwords. Always use bcrypt or similar secure hashing algorithms.

​
Default Avatar Generation

If no avatar URL is provided, the system generates a default avatar using ui-avatars.com: 
avatar: body.avatar || `https://ui-avatars.com/api/?name=${encodeURIComponent(name)}&background=random`

​
User ID Generation

User IDs are automatically generated as UUIDs by Prisma using @default(uuid()).

​
Field Validation

  • Email: Must be unique and max 50 characters
  • Name: Required, max 50 characters
  • Password: Hashed before storage, max 255 characters (hashed)
  • Document Number: Max 20 characters
  • All address fields have specific length constraints as defined in the Prisma schema

Build docs developers (and LLMs) love

Get started for freeTalk to us