# Accounts ## List **get** `/v1/accounts` Lists chat accounts across networks (WhatsApp, Telegram, Twitter/X, etc.) actively connected to this Beeper Desktop instance ### Returns - `accountID: string` Chat account added to Beeper. Use this to route account-scoped actions. - `user: User` User the account belongs to. - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. ### Example ```http curl http://localhost:23373/v1/accounts ``` ## Domain Types ### Account - `Account = object { accountID, user }` A chat account added to Beeper - `accountID: string` Chat account added to Beeper. Use this to route account-scoped actions. - `user: User` User the account belongs to. - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. # Contacts ## Search **get** `/v1/accounts/{accountID}/contacts` Search contacts on a specific account using merged account contacts, network search, and exact identifier lookup. ### Path Parameters - `accountID: string` Account ID this resource belongs to. ### Query Parameters - `query: string` Text to search users by. Network-specific behavior. ### Returns - `items: array of User` - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. ### Example ```http curl http://localhost:23373/v1/accounts/$ACCOUNT_ID/contacts ``` ## List **get** `/v1/accounts/{accountID}/contacts/list` List merged contacts for a specific account with cursor-based pagination. ### Path Parameters - `accountID: string` Account ID this resource belongs to. ### Query Parameters - `cursor: optional string` Opaque pagination cursor; do not inspect. Use together with 'direction'. - `direction: optional "after" or "before"` Pagination direction used with 'cursor': 'before' fetches older results, 'after' fetches newer results. Defaults to 'before' when only 'cursor' is provided. - `"after"` - `"before"` - `limit: optional number` Maximum contacts to return per page. - `query: optional string` Optional search query for blended contact lookup. ### Returns - `hasMore: boolean` True if additional results can be fetched using cursors. - `items: array of User` Merged contacts for the selected account. - `id: string` Stable Beeper user ID. Use as the primary key when referencing a person. - `cannotMessage: optional boolean` True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you. - `email: optional string` Email address if known. Not guaranteed verified. - `fullName: optional string` Display name as shown in clients (e.g., 'Alice Example'). May include emojis. - `imgURL: optional string` Avatar image URL if available. May be temporary or local-only to this device; download promptly if durable access is needed. - `isSelf: optional boolean` True if this user represents the authenticated account's own identity. - `phoneNumber: optional string` User's phone number in E.164 format (e.g., '+14155552671'). Omit if unknown. - `username: optional string` Human-readable handle if available (e.g., '@alice'). May be network-specific and not globally unique. - `newestCursor: string` Cursor for fetching newer results (use with direction='after'). Opaque string; do not inspect. - `oldestCursor: string` Cursor for fetching older results (use with direction='before'). Opaque string; do not inspect. ### Example ```http curl http://localhost:23373/v1/accounts/$ACCOUNT_ID/contacts/list ```