fastify-xhubspot

customObjects.search

Search HubSpot custom object records by a single property value.

customObjects.search

Search records for a given HubSpot custom object type by matching a single property value. Returns all matching records.

Signature

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

Params

Name	Type	Required	Description
`objectType`	`string`	Yes	The custom object type name or ID (e.g., `"subscriptions"`, `"2-12345"`).
`property`	`string`	Yes	The name of the property to filter on (e.g., `"status"`, `"plan_name"`).
`value`	`string`	Yes	The value to match against the specified property. Uses HubSpot `EQ` filter operator.

Returns

Array of { id, properties } for each matching record. Returns an empty array when no records match.

Throws

[xHubspot] customObjects.search requires an objectType — if objectType is missing.
[xHubspot] customObjects.search requires a property — if property is missing.
[xHubspot] customObjects.search requires a value — if value is missing.
Re-throws the HubSpot API error on network failure after logging via fastify.log.error.

Examples

Basic — find all active subscriptions

const active = await fastify.customObjects.search(
  "subscriptions",
  "status",
  "active"
);

console.log(`${active.length} active subscriptions`);

Realistic — look up a subscription by external ID

fastify.get("/subscriptions/by-stripe/:stripeId", async (request, reply) => {
  const records = await fastify.customObjects.search(
    "subscriptions",
    "stripe_subscription_id",
    request.params.stripeId
  );

  if (!records.length) {
    return reply.code(404).send({ error: "Not found" });
  }

  return reply.send(records[0]);
});

AI Context

package: "@xenterprises/fastify-xhubspot"
method: fastify.customObjects.search(objectTypeId, propertyName, value, options?)
use-when: Filter custom object records by a property value
returns: { results, total }

Edit this pageorReport an issue

customObjects.list

List all records for a HubSpot custom object type with optional pagination.

customObjects.update

Update properties on an existing HubSpot custom object record.