Skip to main content

​
POST /api/v1/clients//verify

Verifies a client’s identity based on their billing data (such as plan name, plan price, or residential address). If the data matches cleanly, the client is verified and can proceed with operations like WhatsApp bot interactions.

​
Path Parameters

​
service_id
integer
required
The unique WispHub service identifier of the client to verify.

​
Request Body

​
name
string
The client’s name to verify against. This is compared using partial matching (normalized).
​
address
string
The client’s address to verify. 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 for verification to proceed.

​
Response

Returns a BackendResponse containing verification results.
​
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 or client_verification_failed
​
data
object
Verification result data
​
message
string
Descriptive message about the verification result

​
Example Request

curl -X POST "https://api.wisphub.example/api/v1/clients/12345/verify" \
  -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 verification

{
  "ok": true,
  "type": "success",
  "action": "client_verified",
  "data": {
    "is_valid": true,
    "matched_fields": [
      "name",
      "address",
      "internet_plan_name",
      "internet_plan_price"
    ]
  },
  "message": "Identidad validada de manera exitosa."
}

​
Failed verification

{
  "ok": true,
  "type": "success",
  "action": "client_verification_failed",
  "data": {
    "is_valid": false,
    "matched_fields": [
      "name",
      "address"
    ],
    "debug": {
      "client_address": "V/ Calle 123 #45-67",
      "client_plan_name": "Plan 50MB",
      "resolved_plan_price": 55000.0
    }
  },
  "message": "Los datos proporcionados no coinciden con la información registrada."
}

​
Error Responses

​
400 Bad Request - Insufficient fields
Less than 3 fields were provided for verification
{
  "ok": false,
  "type": "error",
  "action": "client_verification_failed",
  "data": null,
  "message": "Se requieren al menos 3 campos para verificar la identidad (nombre, dirección, plan, precio)."
}
​
404 Not Found
Client with the specified service_id was not found
{
  "ok": false,
  "type": "error",
  "action": "client_not_found",
  "data": null,
  "message": "El cliente especificado no fue encontrado en el sistema."
}

​
Verification Logic

String Matching: The verification 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.
All Fields Must Match: For verification to succeed, ALL fields provided in the request must match. If you provide 4 fields, all 4 must match. If you provide 3 fields, all 3 must match.
If the plan price is not available in the client record, the system will attempt to fetch it from the internet plans API. This may add latency to the request.

​
Use Cases

  • WhatsApp Bot Authentication: Verify users interacting with your WhatsApp bot before granting access to sensitive operations
  • Self-Service Portal: Allow clients to verify their identity before viewing billing information
  • Customer Support: Verify caller identity before providing account details