GET /api/v1/clients/search Performs a flexible search for clients using a general search term. Ideal for finding clients by full name, address, or partial keyword matches when you don’t have the document number or phone number.
Query Parameters Search query string. Can be a partial or full name, address, or any keyword associated with the client. The search is case-insensitive and supports partial matches.
Response Returns a BackendResponse containing an array of matching ClientResponse objects.
Indicates if the request was successful
Response type (e.g., “success”, “error”)
Action identifier: clients_listed (when results found) or client_not_found (when no results)
Array of matching client objects (empty array if no matches found) Show ClientResponse properties
Unique service identifier in WispHub
Client’s identity document (cédula)
Client’s physical address
Client’s locality or neighborhood
IP address of the assigned antenna
Outstanding balance amount
Name of the internet plan
Price of the internet plan
Assigned technician identifier
Optional message providing additional context
Example Request curl -X GET "https://api.wisphub.example/api/v1/clients/search?q=Juan%20Perez" \ -H "Content-Type: application/json"
Example Response Success with results { "ok" : true , "type" : "success" , "action" : "clients_listed" , "data" : [ { "service_id" : 12345 , "name" : "Juan Pérez" , "document" : "1234567890" , "phone" : "+573001234567" , "address" : "Calle 123 #45-67" , "city" : "Bogotá" , "locality" : "Centro" , "payment_status" : "active" , "zone_id" : 5 , "antenna_ip" : "192.168.1.1" , "cut_off_date" : "2026-03-15" , "outstanding_balance" : 0.0 , "lan_interface" : "eth0" , "internet_plan_name" : "Plan 50MB" , "internet_plan_price" : 50000.0 , "technician_id" : 10 }, { "service_id" : 12389 , "name" : "Juan Carlos Pérez" , "document" : "9876543210" , "phone" : "+573009876543" , "address" : "Carrera 45 #12-34" , "city" : "Bogotá" , "locality" : "Norte" , "payment_status" : "active" , "zone_id" : 7 , "antenna_ip" : "192.168.1.5" , "cut_off_date" : "2026-03-20" , "outstanding_balance" : 15000.0 , "lan_interface" : "eth2" , "internet_plan_name" : "Plan 100MB" , "internet_plan_price" : 75000.0 , "technician_id" : 8 } ], "message" : null }
No results found { "ok" : true , "type" : "success" , "action" : "client_not_found" , "data" : [], "message" : null }
Error Responses Search query parameter is missing { "ok" : false , "type" : "error" , "action" : "error" , "data" : null , "message" : "Search query parameter 'q' is required" }
This endpoint is ideal for implementing search-as-you-type functionality in your application. It supports partial matches and is case-insensitive.
For better performance, it’s recommended to use more specific endpoints (by-document, by-phone, by-service-id) when you have exact identifiers available.
