Skip to main content
GET
/
loyalty
/
customers
/
search
Search Customer
curl --request GET \
  --url https://api.example.com/loyalty/customers/search \
  --header 'Authorization: <authorization>'
{
  "success": true,
  "data": {
    "member_code": "<string>",
    "name": "<string>",
    "email": "<string>",
    "whatsapp": "<string>",
    "cpf": "<string>",
    "birth_date": "<string>",
    "points_balance": 123,
    "customer_segment": "<string>",
    "total_spent": 123,
    "transaction_count": 123,
    "last_purchase_date": "<string>",
    "created_at": "<string>",
    "updated_at": "<string>"
  },
  "message": "<string>",
  "timestamp": "<string>"
}

​
Overview

This endpoint allows you to search for existing customers using multiple identification criteria. The search follows priority order: Zupy member code (most specific), WhatsApp (primary identifier), email, and CPF.

​
Authentication

​
Authorization
string
required
Bearer token for API authentication
Authorization: Bearer {your_api_key}

​
Query Parameters

​
whatsapp
string
Customer’s WhatsApp number in international format
+5511965958122 or 11965958122
​
email
string
Customer’s email address
[email protected]
​
cpf
string
Customer’s CPF (with or without formatting)
12345678901 or 123.456.789-01
​
member_code
string
Zupy member code (highest priority)
ZP-12345678

​
Response

​
success
boolean
Indicates if the request was successful
​
data
object
Customer information object
​
message
string
Human-readable response message
​
timestamp
string
Response timestamp in ISO 8601 format

​
Example Request

curl -X GET "https://api.zupy.com/v1/loyalty/customers/search?whatsapp=+5511965958122" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

​
Example Response

{
  "success": true,
  "data": {
    "member_code": "ZP-12345678",
    "name": "João Silva",
    "email": "[email protected]",
    "whatsapp": "+5511965958122",
    "cpf": "12345678901",
    "birth_date": "1990-05-15",
    "points_balance": 1250,
    "customer_segment": "Loyal Customers",
    "total_spent": 2500.00,
    "transaction_count": 15,
    "last_purchase_date": "2024-01-10",
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2024-01-10T14:22:00Z"
  },
  "message": "Customer found successfully",
  "timestamp": "2024-01-15T10:30:00Z"
}

​
Search Priority

The search follows this priority order:
  1. Member Code (ZP-XXXXXXXX) - Most specific identifier
  2. WhatsApp - Primary contact identifier
  3. Email - Secondary identifier
  4. CPF - Document-based identifier
If multiple parameters are provided, only the highest priority match will be returned. For example, if both member_code and whatsapp are provided, the search will use member_code only.

​
Rate Limits

  • Production: 1000 requests per minute
  • Staging: 100 requests per minute

​
Error Codes

CodeDescription
CUSTOMER_NOT_FOUNDNo customer matches the search criteria
VALIDATION_ERRORInvalid format in search parameters
UNAUTHORIZEDMissing or invalid API key
RATE_LIMIT_EXCEEDEDToo many requests