bird contacts list
Usage
Code example
bird contacts list [flags]Description
List the workspace's contacts as a cursor page, newest first. Look one up by exact email, phone_number, or external_id, repeating phone_number to resolve up to 50 numbers in one call (raise limit to match), or search by email, name, or phone substring. Pass include_total for a total count.
Returns a paginated JSON envelope; narrow with the filters below and page with --limit and --starting-after.
Examples
Code example
bird contacts list
bird contacts list | jq -r '.data[].id'
bird contacts list --limit 50 --starting-after <cursor>Options
Filters
| Name | Description |
|---|---|
| Return the contact with exactly this email address (case-insensitive). Email is unique within a workspace, so this matches at most one contact. An empty value is a validation error, never an unfiltered page. | |
| --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. An empty value is a validation error, never an unfiltered page. |
| --identifier | Filter to contacts that have a specific identifier on file. Possible values: email, phone_number. |
| --phone-number <v1,v2,…> | Return the contacts with exactly this phone number in international E.164 form. Repeat the parameter to match any of up to 50 numbers. Set limit to at least the number of values you pass. The default limit is 25, and a page cut short by it looks exactly like numbers that matched nothing. Different identifier parameters still combine with AND, so phone_number=a&phone_number=b&email=c asks for a contact whose phone number is a or b and whose email is c. Encode the leading plus sign as %2B (an unencoded + arrives as a space and is rejected). Phone numbers are unique within a workspace, so each value matches at most one contact. Non-canonical forms of the same number match the contact they canonicalize to; a value that is not a phone number shape, or an empty value, is a validation error, never an unfiltered page. |
| --q | Case-insensitive substring match against the contact's email address, first name, last name, or phone number. Phone matching is over the digits of the international form, so a full pasted number, a formatted number, or trailing digits all match; a national form with a leading trunk zero does not. |
| --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. |
| --include-total | When true, the response includes a total field with the total number of items matching the request's filters across all pages. |
| --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 | Create or update many contacts in one request, matched by the identifiers each entry carries |
| bird contacts create | Create a contact by email address, phone number, or both |
| bird contacts delete | Delete a contact |
| bird contacts get | Get a contact |
| bird contacts update | Update a contact's name, email, phone-number, external-id, or custom data |