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