User.com REST API Docs

# 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.

GET /users/search/?phone_number=_phone_number

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
  • JavaScript
  • PHP
  • Python 
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"

# 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
        }
    ]
}

← Find users by date →