API Reference

Accounts

Contacts

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

List contacts

$client->accounts->contacts->list(string accountID, ?string cursor, ?Direction direction, ?int limit, ?string query): CursorSearch<User>

GET/v1/accounts/{accountID}/contacts/list

List merged contacts for a specific account with cursor-based pagination.

ParametersExpand Collapse

accountID: string

Account ID this resource belongs to.

cursor?:optional string

Opaque pagination cursor; do not inspect. Use together with ‘direction’.

direction?:optional Direction

Pagination direction used with ‘cursor’: ‘before’ fetches older results, ‘after’ fetches newer results. Defaults to ‘before’ when only ‘cursor’ is provided.

limit?:optional int

Maximum contacts to return per page.

query?:optional string

Optional search query for contact lookup.

ReturnsExpand Collapse

User

string id

Stable Beeper user ID. Use as the primary key when referencing a person.

?bool cannotMessage

True if Beeper cannot initiate messages to this user (e.g., blocked, network restriction, or no DM path). The user may still message you.

?string email

Email address if known. Not guaranteed verified.

?string fullName

Display name as shown in clients (e.g., ‘Alice Example’). May include emojis.

?string imgURL

Avatar image URL if available. This may be a remote URL, media URL, data URL, or local file URL depending on the source. May be temporary or available only on this device; download promptly if durable access is needed.

?bool isSelf

True if this user represents the authenticated account’s own identity.

?string phoneNumber

User’s phone number in E.164 format (e.g., ‘+14155552671’). Omit if unknown.

?string username

Human-readable handle if available (e.g., ‘@alice’). May be network-specific and not globally unique.

List contacts

PHP

HTTP

TypeScript

Python

Go

CLI Tool

PHP

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

$client = new Client(accessToken: 'My Access Token');

$page = $client->accounts->contacts->list(
  'accountID',
  cursor: '1725489123456|c29tZUltc2dQYWdl',
  direction: 'before',
  limit: 1,
  query: 'x',
);

var_dump($page);

200 example

{
  "hasMore": true,
  "items": [
    {
      "id": "id",
      "cannotMessage": true,
      "email": "email",
      "fullName": "fullName",
      "imgURL": "imgURL",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "username"
    }
  ],
  "newestCursor": "newestCursor",
  "oldestCursor": "oldestCursor"
}

Returns Examples

200 example

{
  "hasMore": true,
  "items": [
    {
      "id": "id",
      "cannotMessage": true,
      "email": "email",
      "fullName": "fullName",
      "imgURL": "imgURL",
      "isSelf": true,
      "phoneNumber": "phoneNumber",
      "username": "username"
    }
  ],
  "newestCursor": "newestCursor",
  "oldestCursor": "oldestCursor"
}