List Lists

The workspace's people and company lists, most recently updated first unless sort_by names a column. Filter by type, owner (me or a user id) and query (a case-insensitive substring of the name). records_count is what an export of the list would write. metadata.sort_by reports the order actually served: null when none was asked for, or when the workspace holds too many lists to order (the default order is served then). With include_saved_views=true, metadata.saved_views also reports the standing views (every saved person or company, and those saved without a list), one entry each, narrowed by type. Free: costs no credits.

Query parameters

• typeenumoptional

  Only lists of this kind. Omit for both.

  Allowed values: people companies

• ownerstringoptionalmax length: 64

  Whose lists. me for the caller's own, or a user id. Omit for everyone in the workspace.

• querystringoptionalmax length: 100

  Case-insensitive substring of the list name.

• sort_byenumoptional

  Order by this column. Omit for the default order, most recently updated first. metadata.sort_by reports the order actually served.

  Allowed values: name records_count owner created_at updated_at

• sort_directionenumoptional

  Ignored without sort_by. Defaults to the column's own natural direction.

  Allowed values: asc desc

• include_saved_viewsenumoptional

  Also report the standing saved views - all saved people / companies, and those saved without a list - in metadata.saved_views: { type, saved, records_count, last_saved_at } each. Honours type; ignores owner, query and paging. Off by default (four extra reads).

  Allowed values: true false

• pageintegeroptionalmin: 1default: 1

  The page, 1-based.

• per_pageintegeroptionalmin: 1max: 100default: 25

  Lists per page.

Responses

• 200 One page of lists.
• 400 Invalid query (VALIDATION_ERROR; payload.code says which kind of mistake).
• 401 Missing, unknown or inactive credentials (UNAUTHORIZED).
• 429 Over the poll rate limit (RATE_LIMIT); wait Retry-After seconds. Sent only where rate limits are enforced for the caller channel.
• 500 Unexpected server error.

For error handling see Errors. The list fields are described in List object.