TwentyDEV icon

TwentyDEV

Consume the Twenty API
Join our community

Actions252

Overview

This node operation, Find Many People, retrieves multiple person records from the connected service. It is useful for scenarios where you need to query and list people data with flexible filtering, sorting, pagination, and control over the depth of related nested objects included in the response.

Practical examples include:

  • Fetching a list of users or contacts filtered by specific criteria (e.g., those active after a certain date).
  • Retrieving people sorted by name or creation date.
  • Paginating through large datasets of people using cursors.
  • Including related information such as associated organizations or roles up to a specified nesting level.

Properties

Name Meaning
Order By Sorts the returned people records. Accepts a comma-separated list of field names with optional directions. Directions can be: AscNullsFirst, AscNullsLast, DescNullsFirst, DescNullsLast. Default direction is AscNullsFirst. Example: name,createdAtDescNullsLast.
Filter Filters the people records returned. Supports complex expressions combining fields, comparators, and conjunctions. Comparators include eq, neq, in, containsAny, is, gt, gte, lt, lte, startsWith, like, ilike. You can filter on nested fields using dot notation. Supports filtering null and boolean values. Default excludes a zero UUID id. Example: status[eq]:active,and(createdAt[gte]:2023-01-01)
Limit Limits the number of people records returned in one request. Default is 60.
Depth Controls how many levels of nested related objects are included in each person record. Options: 0 (only primary person data), 1 (person plus directly related objects), 2 (person, related objects, and their related objects). Default is 1.
Starting After Returns people starting after a specific cursor value, used for pagination. Cursor values come from the response's pageInfo startCursor or endCursor fields.
Ending Before Returns people ending before a specific cursor value, also used for pagination. Cursor values come from the response's pageInfo startCursor or endCursor fields.

Output

The node outputs JSON data containing an array of people objects matching the query parameters. Each person object includes fields according to the requested depth level, potentially including nested related objects.

The output structure typically includes:

  • A list/array of person records under a key such as data or similar.
  • Pagination info with cursors (startCursor, endCursor) inside a pageInfo object to support cursor-based pagination.
  • Each person object contains standard fields (like id, name, email) and nested related objects depending on the depth parameter.

No binary data output is indicated for this operation.

Dependencies

  • Requires connection to the external Twenty API service.
  • Needs an API authentication token or API key credential configured in n8n to authorize requests.
  • The base URL for the API is set dynamically from credentials.
  • The node uses HTTP headers to accept and send JSON content.

Troubleshooting

  • Empty results: Check your filter syntax and ensure that the filter criteria match existing records. Also verify pagination cursors if using starting_after or ending_before.
  • Invalid filter or order_by format: Ensure filters and sort strings follow the documented syntax exactly, including correct comparator names and conjunction usage.
  • Authentication errors: Verify that the API key or token credential is correctly configured and has sufficient permissions.
  • Pagination issues: If cursors are invalid or expired, reset pagination parameters or fetch fresh cursors from a new query.
  • Depth too high: Requesting very deep nested objects may cause performance issues or timeouts; try reducing the depth parameter.

Links and References

Discussion