Skip to content
API · Customers

Customers identified by phone

Look up customers by id or by their linked WhatsApp number from your external system.

Customer by id

GET /api/v1/external/customers/:id

Returns a tenant's customer. Requires scope customers:read.

Request

curl https://api.nuvlyx.com/api/v1/external/customers/9f8e… \
  -H "Authorization: Bearer nvl_live_YOUR_TOKEN"

Response 200

{
  "id": "9f8e7d…",
  "name": "Juan Pérez",
  "email": "juan@example.com",
  "phone": "+573001234567",
  "phoneVerifiedAt": "2026-05-15T14:00:00.000Z",
  "role": "CLIENT_RETAIL",
  "isActive": true,
  "createdAt": "2026-04-30T09:12:00.000Z"
}

Customer by phone

GET /api/v1/external/customers/by-phone/:phone

Returns the customer whose linked WhatsApp matches the number sent. The customer must have previously linked their WhatsApp (phoneVerifiedAt != null); otherwise the API returns 404 with an explicit message.

Path parameters

ParameterFormatExample
phoneE.164 (with +)%2B573001234567 (URL-encoded)

Request

curl "https://api.nuvlyx.com/api/v1/external/customers/by-phone/%2B573001234567" \
  -H "Authorization: Bearer nvl_live_YOUR_TOKEN"
  1. Customer logs into the store (https://<your-store>.nuvlyx.com).
  2. Goes to My account → Link WhatsApp.
  3. Enters their number and receives a 6-digit code on WhatsApp.
  4. Confirms the code → phone_verified_at gets a timestamp.

From then on, your external system can call any by-phone endpoint and the API recognizes them.

Rules and limits

  • Uniqueness: a phone number can only be linked to one customer per store.
  • OTP rate limit: max 5 codes per hour per customer. Resend requires a 60-second cooldown.
  • OTP expiry: 10 minutes. Max 5 verification attempts per code.
  • Unlinking: the customer can unlink any time from their profile. The API stops recognizing them by phone immediately.