Skip to main content
POST
/
api
/
clients
Create Client
curl --request POST \
  --url https://api.example.com/api/clients \
  --header 'Content-Type: application/json' \
  --data '
{
  "email": "<string>",
  "name": "<string>",
  "surname": "<string>",
  "phone": "<string>",
  "address": "<string>",
  "city": "<string>",
  "country": "<string>",
  "postal_code": "<string>",
  "gender": "<string>",
  "birth_date": "<string>",
  "document_type": "<string>",
  "document_number": "<string>",
  "status": "<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": "<string>",
  "status": "<string>",
  "avatar": "<string>",
  "document_type": "<string>",
  "document_number": "<string>",
  "created_at": "<string>",
  "updated_at": "<string>"
}

​
Overview

Creates a new client (user with USER role) in the system. The endpoint validates all input fields, checks for duplicate emails, and automatically sets a default secure password.

​
Authentication

This endpoint requires authentication. Include a valid session token in your request.

​
Request Body

​
email
string
required
Client’s email address. Must be a valid email format and unique in the system.Validation: Valid email format, max 50 characters
​
name
string
required
Client’s first name.Validation: Minimum 2 characters, max 50 characters
​
surname
string
required
Client’s last name.Validation: Minimum 2 characters, max 50 characters
​
phone
string
required
Client’s phone number.Validation: Minimum 6 characters, max 20 characters
​
address
string
Street address. Defaults to empty string if not provided.Max length: 255 characters
​
city
string
City name. Defaults to empty string if not provided.Max length: 50 characters
​
country
string
Country name. Defaults to empty string if not provided.Max length: 50 characters
​
postal_code
string
Postal/ZIP code. Defaults to empty string if not provided.Max length: 20 characters
​
gender
string
Gender identifier. Defaults to empty string if not provided.Max length: 10 characters
​
birth_date
string
Date of birth in ISO 8601 format. Defaults to current date if not provided.Format: ISO 8601 date string (e.g., “1990-05-15”)
​
document_type
string
Type of identification document. Defaults to DNI.Allowed values: DNI, PASSPORT, NIE
​
document_number
string
Identification document number. Defaults to empty string if not provided.Max length: 20 characters
​
status
string
Account status. Defaults to ON.Allowed values: ON, OFF

​
Response

Returns the created client object. The password field is excluded from the response for security.
​
user_id
string
required
Unique identifier for the client (UUID format)
​
email
string
required
Client’s email address
​
name
string
required
Client’s first name
​
surname
string
required
Client’s last name
​
phone
string
required
Client’s phone number
​
address
string
required
Street address
​
city
string
required
City name
​
country
string
required
Country name
​
postal_code
string
required
Postal/ZIP code
​
gender
string
required
Gender identifier
​
birth_date
string
required
Date of birth in ISO 8601 date format
​
role
string
required
User role - always USER for clients
​
status
string
required
Account status (ON or OFF)
​
avatar
string
required
URL to client’s avatar image (empty string by default)
​
document_type
string
required
Type of identification document
​
document_number
string
required
Identification document number
​
created_at
string
required
Timestamp when the client was created
​
updated_at
string
required
Timestamp when the client was last updated

​
Example Request

cURL
curl --request POST \
  --url 'https://your-domain.com/api/clients' \
  --header 'Content-Type: application/json' \
  --header 'Cookie: your-session-token' \
  --data '{
    "email": "[email protected]",
    "name": "Lucia",
    "surname": "Martin",
    "phone": "+34623456789",
    "address": "Avenida Libertad 45",
    "city": "Barcelona",
    "country": "Spain",
    "postal_code": "08001",
    "gender": "female",
    "birth_date": "1988-03-22",
    "document_type": "DNI",
    "document_number": "87654321B",
    "status": "ON"
  }'

​
Example Response

{
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "email": "[email protected]",
  "name": "Lucia",
  "surname": "Martin",
  "phone": "+34623456789",
  "address": "Avenida Libertad 45",
  "city": "Barcelona",
  "country": "Spain",
  "postal_code": "08001",
  "gender": "female",
  "birth_date": "1988-03-22",
  "role": "USER",
  "status": "ON",
  "avatar": "",
  "document_type": "DNI",
  "document_number": "87654321B",
  "created_at": "2024-03-05T09:15:00.000Z",
  "updated_at": "2024-03-05T09:15:00.000Z"
}

​
Error Responses

​
409 Conflict - Duplicate Email

Returned when the email address is already registered in the system. 
{
  "statusCode": 409,
  "statusMessage": "El correo electrónico ya está registrado"
}

​
400 Bad Request - Validation Error

Returned when the request body fails validation. 
{
  "statusCode": 400,
  "statusMessage": "Email inválido"
}
Common validation errors:
  • Email inválido - Invalid email format
  • El nombre es obligatorio - Name must be at least 2 characters
  • El apellido es obligatorio - Surname must be at least 2 characters
  • El teléfono es obligatorio - Phone must be at least 6 characters

​
Implementation Details

  • The endpoint automatically sets role: 'USER' for all created clients
  • A default password beils12345 is set (hashed with bcrypt, salt rounds: 10)
  • The avatar field is initialized as an empty string
  • Email uniqueness is enforced at the database level
  • The password field is always excluded from responses
  • All optional string fields default to empty strings if not provided
  • The birth_date is stored as a Date object in the database
  • Input validation is performed using Zod schemas

​
Security Notes

  • Passwords are hashed using bcrypt before storage
  • The default password should be changed by the client on first login
  • Consider implementing a password reset flow for new clients

​
Source Reference

Implemented in server/api/clients/index.post.ts

Build docs developers (and LLMs) love

Get started for freeTalk to us