Skip to content
Browse docslist_people

list_people

Reads one page of identities in your own private Rolodex, including manually added people without email or profiles. Use it to find the person the member means before reading details or editing. It reads no other member’s relationships.

InputRequiredMeaning
filternoOne quoted name/email substring, or emails : "address@example.com" for an exact address. Omitted or empty lists all owned people.
pageSizenoMaximum identities to return. Default and zero mean 20; values above 100 are capped. Negative or fractional values are invalid.
pageTokennoThe preceding page’s nextPageToken, with the same filter. Omit or use an empty string for the first page.

Matching ignores case, accents, and repeated spaces. A text filter matches the displayed name or any email. Filters contain 2–200 searchable characters, with at most 512 characters in the complete expression. Unsupported fields, operators, or malformed expressions fail with invalid_argument; they are never silently ignored. This is identity lookup, not suitability ranking.

The response is { people, nextPageToken }. Each person contains only personId, displayName, and emails. Display name uses the owner’s label, then the contact’s name, then an email, then “Unnamed person.” Results are ordered by latest interaction first, then person ID. A short or empty page is complete only when nextPageToken is empty. Tokens expire after one hour and grant no authority; every page checks current ownership.

json
{
  "filter": "\"Pat\"",
  "pageSize": 20
}
json
{
  "people": [{ "personId": "00000000-0000-4000-a000-000000000005", "displayName": "Synthetic Pat", "emails": ["pat@example.test"] }],
  "nextPageToken": ""
}

Use get_person to distinguish plausible candidates. Names alone do not prove identity. Continue or narrow incomplete results before deciding no existing person matches; ask the member when ambiguity remains. Reading creates nothing and schedules no work.

Annotations: readOnlyHint: true · destructiveHint: false · idempotentHint: true · openWorldHint: false