# `bird contacts list`

## Usage

```bash
bird contacts list [flags]
```

## Description

List the workspace's contacts as a cursor page, newest first. Look one up by exact email or external_id, or search by email substring.

Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.

## Examples

```bash
bird contacts list
bird contacts list | jq -r '.data[].id'
bird contacts list --limit 50 --starting-after <cursor>
```

## Options

#### Filters

| Name                | Description                                                                                                                                             |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `--email`           | Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact.         |
| `--external-id`     | Return the contact with exactly this external_id (your own identifier for the contact). Unique within a workspace, so this matches at most one contact. |
| `--q`               | Case-insensitive substring match against the contact's email address.                                                                                   |
| `--response-schema` | Print the fields this command returns, then exit                                                                                                        |

#### Pagination

| Name               | Description                                                                                                                                    |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `--ending-before`  | Cursor from the prev_cursor field of a previous list response. Returns items immediately before the cursor position in the current sort order. |
| `--limit <n>`      | Maximum number of items to return per page.                                                                                                    |
| `--starting-after` | Cursor from the next_cursor field of a previous list response. Returns items immediately after the cursor position in the current sort order.  |

## Related

| Name                                                          | Description                                                      |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| [`bird contacts batch`](/docs/cli/reference/contacts-batch)   | Create or update many contacts in one request, matched by email. |
| [`bird contacts create`](/docs/cli/reference/contacts-create) | Create a contact by email address.                               |
| [`bird contacts delete`](/docs/cli/reference/contacts-delete) | Delete a contact                                                 |
| [`bird contacts get`](/docs/cli/reference/contacts-get)       | Get a contact                                                    |
| [`bird contacts update`](/docs/cli/reference/contacts-update) | Update a contact's name, email, external-id, or custom data.     |