Search users
GET /v0/search-users
Search users across on a specific account using the network’s search API. Only use for creating new chats. Use GET /v1/accounts/{accountID}/contacts instead.
Parameters
Section titled “ Parameters ”Query Parameters
Section titled “Query Parameters ”Beeper account ID this resource belongs to.
Beeper account ID this resource belongs to.
Text to search users by. Network-specific behavior.
Text to search users by. Network-specific behavior.
Responses
Section titled “ Responses ”Tool executed successfully
object
A person on or reachable through Beeper. Values are best-effort and can vary by network.
object
Stable Beeper user ID. Use as the primary key when referencing a person.
Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique.
User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown.
Email address if known. Not guaranteed verified.
Display name as shown in clients (e.g., ‘Alice Example’). May include emojis.
Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed.
True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.
True if this user represents the authenticated account’s own identity.
Invalid request parameters
object
Error message
Error code
Additional error details
object
Access token is missing or invalid
object
Error message
Error code
Additional error details
object
Access token does not have the required scope
object
Error message
Error code
Additional error details
object
Resource not found
object
Error message
Error code
Additional error details
object
Unprocessable entity - validation error
object
Error message
Error code
Additional error details
object
Too many requests - rate limit exceeded
object
Error message
Error code
Additional error details
object
Internal server error
object
Error message
Error code
Additional error details