hubspot-list-associations
Read-only
Retrieve relationships between HubSpot objects to map data connections. Find associated records like companies linked to contacts or deals related to companies using object IDs.
Instructions
🎯 Purpose:
1. Retrieves existing relationships between a specific object and other objects of a particular type.
2. For example, you can find all companies that a contact is associated with, all deals related to a company, or discover which customers have an open ticket.
📦 Returns:
1. Collection of associated object IDs and relationship metadata.
2. Use hubspot-batch-read-objects to get more information about the associated objects.
🧠Usage Guidance:
1. Use this tool when mapping relationships between different HubSpot objects to understand your data's connections.
2. This tool is ideal when you already know a specific record's ID and need to discover its relationships with other object types.
3. Prefer this over hubspot-search-objects tool when exploring established connections rather than filtering by properties or criteria.Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| objectType | Yes | The type of HubSpot object to get associations from. Valid values include: appointments, companies, contacts, courses, deals, leads, line_items, listings, marketing_events, meetings, orders, postal_mail, products, quotes, services, subscriptions, tickets, users. For custom objects, use the hubspot-get-schemas tool to get the objectType. | |
| objectId | Yes | The ID of the HubSpot object to get associations from | |
| toObjectType | Yes | The type of HubSpot object to get associations to. Valid values include: appointments, companies, contacts, courses, deals, leads, line_items, listings, marketing_events, meetings, orders, postal_mail, products, quotes, services, subscriptions, tickets, users. For custom objects, use the hubspot-get-schemas tool to get the objectType. | |
| after | No | Paging cursor token for retrieving the next page of results |
Implementation Reference
- The `process` method of `AssociationsListTool` that implements the core logic: builds the HubSpot CRM v4 API endpoint for associations and retrieves the results with pagination support.
async process(args) { try { // Build the API path let endpoint = `/crm/v4/objects/${args.objectType}/${args.objectId}/associations/${args.toObjectType}?limit=500`; // Add pagination parameter if provided if (args.after) { endpoint += `&after=${args.after}`; } // Make API request const response = await this.client.get(endpoint); return { content: [ { type: 'text', text: JSON.stringify(response, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error retrieving HubSpot associations: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } - Zod input schema defining parameters: objectType (from), objectId, toObjectType (to), and optional after for pagination.
const AssociationsListSchema = z.object({ objectType: z .string() .describe(`The type of HubSpot object to get associations from. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`), objectId: z.string().describe('The ID of the HubSpot object to get associations from'), toObjectType: z .string() .describe(`The type of HubSpot object to get associations to. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`), after: z .string() .optional() .describe('Paging cursor token for retrieving the next page of results'), }); - dist/tools/toolsRegistry.js:32-32 (registration)Instantiation and registration of the `AssociationsListTool` using the `registerTool` function.
registerTool(new AssociationsListTool());