bird contacts list

Usage

Code example

bird contacts list [flags]

List the workspace's contacts as a cursor page, newest first. Look one up by exact email, phone_number, or external_id, 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
--email	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	Return the contact with exactly this phone number in international E.164 form. Encode the leading plus sign as %2B (an unencoded + arrives as a space and is rejected). Phone numbers are unique within a workspace, so this 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.

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