fastify-xhubspot

contacts.search

Search HubSpot contacts by matching a single property with an equality filter.

contacts.search

Search HubSpot contacts where a given property equals a specified value. Returns up to 100 results.

Signature

fastify.contacts.search(
  property: string,
  value: string | number
): Promise<Array<{ id: string; properties: Record<string, string> }>>

Params

Name	Type	Required	Description
`property`	`string`	Yes	HubSpot property name to filter on (e.g., `"company"`, `"hs_lead_status"`).
`value`	`string \| number`	Yes	Value to match against. Converted to string before sending to the API.

Returns

Array of matching contacts, each with { id, properties }. Empty array if none match.

Throws

[xHubspot] contacts.search requires a property string — if property is missing or not a string.
[xHubspot] contacts.search requires a value — if value is null or undefined.
Re-throws the HubSpot API error on failure.

Examples

Basic — find contacts at a company

const contacts = await fastify.contacts.search("company", "Acme Corp");

Realistic — find all new leads

fastify.get("/crm/new-leads", async () => {
  const leads = await fastify.contacts.search("hs_lead_status", "NEW");
  return leads.map(c => ({
    id: c.id,
    email: c.properties.email,
    name: `${c.properties.firstname} ${c.properties.lastname}`,
  }));
});

AI Context

package: "@xenterprises/fastify-xhubspot"
method: fastify.contacts.search(propertyName, value, options?)
use-when: Filter HubSpot contacts by a single property value
returns: { results, total }

Edit this pageorReport an issue

contacts.list

Page through all HubSpot contacts with optional limit and cursor-based pagination.

contacts.update

Update properties on an existing HubSpot contact.