GET/users/search/?phone_number=_phone_number

Find users by phone number

You can find a user based on the phone_number attribute. If you want to list all of your users with a specific phone number, add a "many=true" parameter to your request.

Attributes	Type	Required	Description
phone_number	string	yes	A user phone number.

Handling phone number formats

When searching for phone numbers, you might encounter various formats in the database. While we recommend storing numbers in clean format (+48123456789) the search endpoint will handle other formats as well.

Common phone number variations:

• International with formatting: +1 (555) 123-4567
• With spaces and hyphens: 48 123-456-789
• Clean format: +48123456789

When making API requests:

1. Using HTTP Client Libraries (Recommended)

   • Most modern HTTP clients handle URL encoding automatically
   • Example with Python requests:

   # Clean format (recommended for consistency)
   params = {
       "phone_number": "+48123456789"
   }
   
   # Will also work with formatted numbers
   params = {
       "phone_number": "+48 123-456-789"
   }
   response = requests.get(url, params=params, headers=headers)

2. Manual URL Encoding

   • If building the URL manually, make sure to encode all special characters:

   from urllib.parse import quote
   
   # With formatting
   phone_formatted = "+48 123-456-789"
   phone_encoded = quote(phone_formatted)  # Results in: %2B48%20123-456-789
   
   # Clean format
   phone_clean = "+48123456789"
   phone_encoded = quote(phone_clean)  # Results in: %2B48123456789
   
   url = f"{base_url}?phone_number={phone_encoded}"

Request

CURL

curl -X GET -H "Authorization: Token <your_64_char_api_key>"
-H "Accept: */*; version=2"
"https://<your_app_subdomain>.user.com/api/public/users/search/?phone_number=:phone_number"

JavaScript

var data = null;
    
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === 4) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://<your_app_subdomain>.user.com/api/public/users/search/?phone_number=:phone_number");
xhr.setRequestHeader("authorization", "Token <your_64_char_api_key>");
xhr.setRequestHeader("accept", "*/*; version=2");

xhr.send(data);

PHP

<?phpF
    
$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://<your_app_subdomain>.user.com/api/public/users/search/?phone_number=:phone_number",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => array(
      "Accept: */*; version=2",
    "authorization: Token <your_64_char_api_key>"
  ),
));

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

Python

import http.client
    
conn = http.client.HTTPSConnection("<your_app_subdomain>.user.com")

headers = { 'authorization': "Token <your_64_char_api_key>", "Accept": "*/*; version=2" }

conn.request("GET", "/api/public/users/search/?phone_number=:phone_number", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

Response

{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1947,
            "user_key": "g7lvoickax9e",
            "name": "John Doe",
            "email": "johndoe+1@example.com",
            "gender": "unknown",
            "status": "user",
            "phone_number": "48 123-456-789",
            "first_seen": "2025-04-07T08:59:22.364896Z",
            "last_seen": "2025-04-07T09:25:44.809546Z",
            "page_views": 14,
            "last_ip": "54.38.139.0",
            "timezone": "Europe/Kaliningrad",
            "city": "Warsaw",
            "region": "Mazovia",
            "country": "Poland",
            "unsubscribed": false,
            "browser_language": "pl",
            "widget_language": null,
            "score": 0,
            "browser": "Chrome",
            "os_type": "Mac OS X",
            "resolution": "2560x1440",
            "created_at": "2025-04-07T08:59:22.381018Z",
            "updated_at": "2025-04-08T11:21:29.044044Z",
            "companies": [
                {
                    "name": "Example",
                    "id": 21,
                    "member_since": "2024-03-21T13:43:54.542482Z"
                }
            ],
            "gravatar_url": null,
            "lists": [],
            "tags": [],
            "notifications": true,
            "facebook_url": null,
            "linkedin_url": null,
            "twitter_url": null,
            "google_url": null,
            "last_contacted": "2025-04-07T09:28:07.247131Z",
            "custom_id": null,
            "web_push_subscription": false,
            "assigned_to": null,
            "most_active_time": null,
            "lt_opened_email": null,
            "lt_clicked_email": null,
            "email_mx_valid": true,
            "referrer": "https://srv71624.seohost.com.pl/test-site/koszyk/",
            "last_heard_from": "2025-04-07T09:12:28.758234Z",
            "spambounced": false,
            "softbounced": false,
            "hardbounced": false,
            "marked_email_as_spam": true
        }
    ]
}