Skip to main content

​
POST /api/v1/clients/resolve

Identifies and verifies a client in a single call, without needing to know their service_id beforehand. The endpoint searches for candidate clients by name and tests each one against the provided data. Useful for users without a registered document or phone number.

​
Request Body

​
name
string
The client’s name to search and verify. Used as the primary search criterion if provided.
​
address
string
The client’s address to verify. Used as a fallback search criterion if name is not provided. Common prefixes like “V/”, “VDA/”, “VEREDA”, “BARRIO”, “B/” are automatically normalized.
​
internet_plan_name
string
The name of the internet plan to verify.
​
internet_plan_price
float
The price of the internet plan to verify. Allows a tolerance of ±1.0 for matching.
At least 3 of the 4 fields (name, address, internet_plan_name, internet_plan_price) must be provided. The endpoint requires sufficient data to accurately identify and verify the client.

​
Response

Returns a BackendResponse containing the identified and verified client.
​
ok
boolean
required
Indicates if the request was successful
​
type
string
required
Response type (e.g., “success”, “error”)
​
action
string
required
Action identifier: client_verified, client_not_found, or client_verification_failed
​
data
object
The identified client’s complete information
​
message
string
Descriptive message about the resolution result

​
Example Request

curl -X POST "https://api.wisphub.example/api/v1/clients/resolve" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Juan Pérez",
    "address": "Calle 123",
    "internet_plan_name": "Plan 50MB",
    "internet_plan_price": 50000.0
  }'

​
Example Response

​
Successful resolution

{
  "ok": true,
  "type": "success",
  "action": "client_verified",
  "data": {
    "service_id": 12345,
    "name": "Juan Pérez",
    "document": "1234567890",
    "phone": "+573001234567",
    "address": "V/ 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
  },
  "message": "Cliente identificado y verificado exitosamente."
}

​
Error Responses

​
400 Bad Request - Insufficient fields
Less than 3 fields were provided
{
  "ok": false,
  "type": "error",
  "action": "client_verification_failed",
  "data": null,
  "message": "Se requieren al menos 3 campos para resolver la identidad (nombre, dirección, plan, precio)."
}
​
404 Not Found - No candidates
No clients were found matching the search query
{
  "ok": false,
  "type": "error",
  "action": "client_not_found",
  "data": null,
  "message": "No se encontraron clientes con los datos proporcionados."
}
​
404 Not Found - No match
Candidates were found but none matched all the provided data
{
  "ok": false,
  "type": "error",
  "action": "client_not_found",
  "data": null,
  "message": "Ningún cliente coincide con todos los datos proporcionados."
}

​
How It Works

  1. Search Phase: The endpoint first searches for candidate clients using the name (or address if name is not provided) as the search query
  2. Scoring Phase: Each candidate is scored based on how many fields match the provided data
  3. Verification Phase: A candidate is considered verified only if ALL provided fields match

​
Verification Logic

String Matching: Uses normalized partial string matching. For addresses, common prefixes like “V/”, “VDA/”, “VEREDA”, “BARRIO”, and “B/” are automatically stripped before comparison.
Price Tolerance: When comparing prices, a tolerance of ±1.0 is allowed to account for rounding differences.
Perfect Match Required: The client is only verified if the number of matched fields equals the number of fields provided. Partial matches are rejected to ensure identity accuracy.

​
Comparison with Verify Endpoint

Feature/resolve/verify
Requires service_idNoYes
Searches for clientYesNo
Returns client dataYesNo (returns verification result)
Use caseDon’t know service_idAlready have service_id
This endpoint performs both search and verification, which may be slower than the direct verify endpoint. Use this when you don’t have the service_id. If you already have the service_id, use the Verify endpoint instead.

​
Use Cases

  • WhatsApp Bot Onboarding: First-time users who don’t have document or phone registered can identify themselves
  • Self-Service Portal: Allow clients to find their account using billing information
  • Customer Support: Identify callers who don’t remember their account number
  • Alternative Verification: Verify identity when traditional methods (document/phone) are not available