Twenty icon

Twenty

Interact with the Twenty API

Actions25

Person → Bulk Match

AI-generated

Overview

This node interacts with the Twenty API to perform bulk matching of person records. It allows users to match multiple person entries against the Twenty workspace data, either by manually configuring match candidates, using an array from incoming items, or by providing raw JSON data. This is useful for scenarios where you need to identify or verify multiple people in bulk, such as syncing contact lists, deduplicating records, or enriching data with existing Twenty workspace information.

Use Case Examples

  1. Bulk match a list of people by manually entering their details in the node to find corresponding records in Twenty.
  2. Use an incoming array of people from previous workflow steps to perform bulk matching automatically.
  3. Paste a JSON array describing people to match them in bulk against the Twenty workspace.

Properties

Name Meaning
Base URL Base URL for the Twenty workspace REST API, including the /rest suffix.
Match Source Determines how match candidates are provided: manually configured, from incoming items, or raw JSON input.
Match Entries Collection of person details to match, including city, company ID, first name, job title, last name, and primary email. Used when Match Source is 'Builder'.
Input Property Name Dot notation path to the array on the incoming item that holds the match candidates. Used when Match Source is 'From Incoming Items'.
People (JSON) JSON array describing the match candidates, e.g., [{"emails":{"primaryEmail":"user@example.com"}}]. Used when Match Source is 'Raw JSON'.
Depth Controls whether related records are expanded in the response: primary record only or include direct relations.
Request Options Additional request settings such as batching, SSL certificate validation, proxy, and timeout.

Output

JSON

  • matches - Array of matched person records returned from the Twenty API bulk match operation.

Dependencies

  • Requires an API key credential for authenticating with the Twenty API.

Troubleshooting

  • Ensure the Base URL is correctly set to your Twenty workspace REST API endpoint including the /rest suffix.
  • If using 'From Incoming Items' match mode, verify the input property name correctly points to an array of match candidates in the incoming data.
  • When using raw JSON input, ensure the JSON is properly formatted and represents an array of person objects.
  • Batching settings should be adjusted to avoid hitting API rate limits; too large batch sizes or too frequent requests may cause errors.
  • If SSL certificate validation errors occur, consider enabling 'Ignore SSL Issues' but be aware of security implications.
  • Proxy settings must be correctly configured if your network requires it for outbound HTTP requests.

Discussion