Skip to main content
GET
/
api
/
users
/
search
Search Users
curl --request GET \
  --url https://api.example.com/api/users/search
{
  "users": [
    {
      "id": 123,
      "username": "<string>",
      "email": "<string>",
      "password_hash": "<string>",
      "firstname": "<string>",
      "lastname": "<string>",
      "phone_number": "<string>",
      "role": "<string>",
      "is_active": true,
      "profileImage": "<string>",
      "created_at": {},
      "updated_at": {}
    }
  ]
}

​
Overview

This endpoint allows you to search for users by their username or email address. The search is case-insensitive and matches partial strings.

​
Request

​
q
string
required
Search query to match against username or email. The search is case-insensitive and matches partial strings.
curl -X GET 'http://localhost:8080/api/users/search?q=john' \
  -H 'Content-Type: application/json'

​
Response

​
users
array
Array of user objects matching the search criteria
​
id
long
Unique identifier for the user
​
username
string
User’s username
​
email
string
User’s email address
​
password_hash
string
Encrypted password hash
​
firstname
string
User’s first name
​
lastname
string
User’s last name
​
phone_number
string
User’s phone number
​
role
string
User’s role in the system (e.g., ADMIN, USER, DRIVER)
​
is_active
boolean
Whether the user account is active
​
profileImage
string
URL or path to the user’s profile image
​
created_at
timestamp
Timestamp when the user was created
​
updated_at
timestamp
Timestamp when the user was last updated

​
Example Response

[
  {
    "id": 1,
    "username": "johndoe",
    "email": "[email protected]",
    "password_hash": "$2a$10$...",
    "firstname": "John",
    "lastname": "Doe",
    "phone_number": "+1234567890",
    "role": "USER",
    "is_active": true,
    "profileImage": "/images/profiles/johndoe.jpg",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:45:00Z"
  },
  {
    "id": 4,
    "username": "johnsmith",
    "email": "[email protected]",
    "password_hash": "$2a$10$...",
    "firstname": "John",
    "lastname": "Smith",
    "phone_number": "+1234567892",
    "role": "DRIVER",
    "is_active": true,
    "profileImage": "/images/profiles/johnsmith.jpg",
    "created_at": "2024-01-18T11:20:00Z",
    "updated_at": "2024-01-23T09:15:00Z"
  }
]

​
Search Behavior

  • The search is case-insensitive
  • Matches are found in both username and email fields
  • Partial matches are supported (e.g., “john” will match “johndoe” and “[email protected]”)
  • Returns an empty array if no matches are found

​
Example Queries

# Search for users with "admin" in username or email
curl -X GET 'http://localhost:8080/api/users/search?q=admin'

# Search for users with "@gmail.com" in their email
curl -X GET 'http://localhost:8080/api/users/[email protected]'

# Search for users with "smith" in username or email
curl -X GET 'http://localhost:8080/api/users/search?q=smith'

Build docs developers (and LLMs) love

Get started for freeTalk to us