> For the complete documentation index, see [llms.txt](https://docs.ebbot.ai/ebbot-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ebbot.ai/ebbot-docs/integrations/automations-integrations/integration-setup-guides/hubspot-integration-in-automations/actions/search-contacts.md).

# 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](/ebbot-docs/integrations/automations-integrations/integration-setup-guides/hubspot-integration-in-automations/troubleshooting.md) for request errors and retry behavior, or return to the [action catalog](/ebbot-docs/integrations/automations-integrations/integration-setup-guides/hubspot-integration-in-automations/actions.md).