Search Contacts

Searches for contacts in HubSpot using a free text query, for example a name, email address or phone number. Useful for finding a contact's ID when you only know who they are.

Action identifier: search_contacts. Reference checked: 29 September 2026.

Inputs

Field	Type	Required/default	Meaning
query	string	Required	Search for contacts by name, email address, or phone number
limit	integer	100	The maximum number of contacts to return

Output shape

Paths are relative to this action's output. Select them from the builder's variable picker; do not add a ticket wrapper to actions that return top-level fields. Nullable property fields and empty defaults are not proof that a value was retrieved.

Path	Type	Meaning
results	list of objects	Records returned by this execution; see the retrieval limits below.
results[].id	string	HubSpot record ID.
results[].properties	object	Property values returned for this record; some declared fields may be empty.
results[].properties.firstname	string | null	First name of the contact
results[].properties.lastname	string | null	Last name of the contact
results[].properties.email	string | null	Email address of the contact
results[].properties.phone	string | null	Phone number of the contact
results[].properties.company	string | null	Company name
results[].properties.website	string | null	Website URL
results[].createdAt	string	Creation timestamp returned by HubSpot; empty when unavailable.
results[].updatedAt	string	Last-update timestamp returned by HubSpot; empty when unavailable.
results[].archived	boolean	Archive flag returned by HubSpot; defaults to false when omitted.
exists	boolean	True when HubSpot returns matches, before the action applies limit locally.

Property objects can contain additional fields returned by HubSpot. The declared fields above are not a promise that every property is populated.

Behavior and limits

Runs one free-text search using the query, then applies limit to the returned list locally. The action does not send that limit to the search API, follow pagination or expose a next-page cursor. A larger limit does not retrieve more than HubSpot's returned page.

No returned matches gives exists: false. Use Search CRM Objects for explicit properties, filters and cursor paging. Search results should not be treated as an immediate authoritative read after a write.

Requested properties

This action explicitly requests email, firstname, lastname, phone, hs_object_id, createdate, lastmodifieddate. Other fields declared in its output model are not automatically fetched.

See Troubleshooting for request errors and retry behavior, or return to the action catalog.