Skip to main content
GET
/
api
/
clients
List Clients
curl --request GET \
  --url https://api.example.com/api/clients
{
  "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>",
  "_count": {
    "client_bookings": 123,
    "consents": 123,
    "debts": 123
  },
  "statusCode": 123,
  "statusMessage": "<string>"
}

​
Overview

Returns a list of all users with the USER role (clients) in the system. Supports optional text search across multiple fields. The response includes booking, consent, and debt counts for each client.

​
Authentication

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

​
Query Parameters

​
search
string
Filter clients by searching across name, surname, email, or phone number. The search is case-sensitive and uses partial matching.Example: search=john will match clients with “John” in their name, surname, email, or phone.

​
Response

Returns an array of client objects. The password field is excluded from all responses for security.
​
user_id
string
required
Unique identifier for the client (UUID format, max 100 characters)
​
email
string
required
Client’s email address (max 50 characters)
​
name
string
required
Client’s first name (max 50 characters)
​
surname
string
required
Client’s last name (max 50 characters)
​
phone
string
required
Client’s phone number (max 20 characters)
​
address
string
required
Street address (max 255 characters)
​
city
string
required
City name (max 50 characters)
​
country
string
required
Country name (max 50 characters)
​
postal_code
string
required
Postal/ZIP code (max 20 characters)
​
gender
string
required
Gender identifier (max 10 characters)
​
birth_date
string
required
Date of birth in ISO 8601 date format
​
role
string
required
User role - always USER for clients (enum: ADMIN, USER)
​
status
string
required
Account status (enum: ON, OFF). Default is ON
​
avatar
string
required
URL to client’s avatar image (max 255 characters)
​
document_type
string
required
Type of identification document (enum: DNI, PASSPORT, NIE). Default is DNI
​
document_number
string
required
Identification document number (max 20 characters)
​
created_at
string
required
Timestamp when the client was created (ISO 8601 format)
​
updated_at
string
required
Timestamp when the client was last updated (ISO 8601 format)
​
_count
object
required
Aggregate counts of related records
​
client_bookings
number
Total number of bookings made by this client
​
consents
number
Total number of consent documents signed
​
debts
number
Total number of debt records

​
Example Request

cURL
curl --request GET \
  --url 'https://your-domain.com/api/clients' \
  --header 'Cookie: your-session-token'
cURL with search
curl --request GET \
  --url 'https://your-domain.com/api/clients?search=maria' \
  --header 'Cookie: your-session-token'

​
Example Response

[
  {
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "[email protected]",
    "name": "Maria",
    "surname": "Garcia",
    "phone": "+34612345678",
    "address": "Calle Mayor 123",
    "city": "Madrid",
    "country": "Spain",
    "postal_code": "28013",
    "gender": "female",
    "birth_date": "1990-05-15",
    "role": "USER",
    "status": "ON",
    "avatar": "",
    "document_type": "DNI",
    "document_number": "12345678A",
    "created_at": "2024-01-15T10:30:00.000Z",
    "updated_at": "2024-03-01T14:20:00.000Z",
    "_count": {
      "client_bookings": 12,
      "consents": 2,
      "debts": 0
    }
  }
]

​
Error Responses

​
statusCode
number
HTTP status code
​
statusMessage
string
Error message

​
500 Internal Server Error

{
  "statusCode": 500,
  "statusMessage": "Error al obtener clientes"
}

​
Implementation Details

  • Clients are filtered by role: 'USER' to exclude admin users
  • Results are ordered by created_at in descending order (newest first)
  • The password field is always excluded from responses
  • Search performs partial matching across name, surname, email, and phone fields using OR logic
  • Related counts are computed for bookings, consents, and debts

​
Source Reference

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

Build docs developers (and LLMs) love

Get started for freeTalk to us