X Enterprises
fastify-xhubspot

customObjects.associate / customObjects.getAssociations

Create or read associations between a HubSpot custom object record and other CRM objects.

customObjects.associate / customObjects.getAssociations

Create a new association between a custom object record and another CRM object, or read all existing associations of a given type.

Signatures

fastify.customObjects.associate(
  objectType: string,
  objectId: string,
  toObjectType: string,
  toObjectId: string,
  associationTypeId?: string
): Promise<true>

fastify.customObjects.getAssociations(
  objectType: string,
  objectId: string,
  associationType: string
): Promise<Array<{ id: string; type: string }>>

Params

associate

NameTypeRequiredDescription
objectTypestringYesThe source custom object type name or ID (e.g., "subscriptions").
objectIdstringYesHubSpot record ID of the source custom object.
toObjectTypestringYesTarget object type (e.g., "contacts", "companies", "deals").
toObjectIdstringYesHubSpot record ID of the target object.
associationTypeIdstringNoCustom association type ID. Uses the HubSpot default association type when omitted.

getAssociations

NameTypeRequiredDescription
objectTypestringYesThe source custom object type name or ID.
objectIdstringYesHubSpot record ID of the source custom object.
associationTypestringYesTarget object type to read associations for (e.g., "contacts", "deals").

Returns

associate

true on success.

getAssociations

Array of { id, type } for each associated record.

Throws

  • [xHubspot] customObjects.associate requires an objectType — if objectType is missing.
  • [xHubspot] customObjects.associate requires an objectId — if objectId is missing.
  • [xHubspot] customObjects.associate requires a toObjectType — if toObjectType is missing.
  • [xHubspot] customObjects.associate requires a toObjectId — if toObjectId is missing.
  • [xHubspot] customObjects.getAssociations requires an objectType
  • [xHubspot] customObjects.getAssociations requires an objectId
  • [xHubspot] customObjects.getAssociations requires an associationType
  • Re-throws HubSpot API errors on network failure after logging via fastify.log.error.

Examples

associate — link a subscription record to a contact

await fastify.customObjects.associate(
  "subscriptions",
  "1001",
  "contacts",
  "12345"
);

associate — link with a specific association type

await fastify.customObjects.associate(
  "subscriptions",
  "1001",
  "companies",
  "67890",
  "98" // custom association type ID
);

getAssociations — find all contacts linked to a subscription

const contacts = await fastify.customObjects.getAssociations(
  "subscriptions",
  "1001",
  "contacts"
);
// [{ id: "12345", type: "SUBSCRIPTION_TO_CONTACT" }]

Realistic — create and immediately link a record

fastify.post("/subscriptions", async (request, reply) => {
  const { planName, billingCycle, contactId, companyId } = request.body;

  const subscription = await fastify.customObjects.create("subscriptions", {
    plan_name: planName,
    billing_cycle: billingCycle,
    status: "active",
  });

  await Promise.all([
    fastify.customObjects.associate("subscriptions", subscription.id, "contacts", contactId),
    fastify.customObjects.associate("subscriptions", subscription.id, "companies", companyId),
  ]);

  return reply.code(201).send({ subscriptionId: subscription.id });
});

See also

AI Context

package: "@xenterprises/fastify-xhubspot"
methods: fastify.customObjects.associate(objectTypeId, recordId, toObjectId, toObjectType) | fastify.customObjects.getAssociations(objectTypeId, recordId, toObjectType)
use-when: Create or read associations between a custom object record and other HubSpot objects
returns: associate → void | getAssociations → { results }

contacts.update

Update properties on an existing HubSpot contact.

customObjects.batchCreate

Create multiple HubSpot custom object records in a single API call.

Copyright © 2026