hubspot-list-associations
Retrieve relationships between specific HubSpot objects, such as companies linked to a contact or deals associated with a company, using object IDs. Ideal for mapping data connections efficiently.
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
| Name | Required | Description | Default |
|---|---|---|---|
| after | No | Paging cursor token for retrieving the next page of results | |
| objectId | Yes | The ID of the HubSpot object to get associations from | |
| 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. | |
| 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. |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"after": {
"description": "Paging cursor token for retrieving the next page of results",
"type": "string"
},
"objectId": {
"description": "The ID of the HubSpot object to get associations from",
"type": "string"
},
"objectType": {
"description": "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.",
"type": "string"
},
"toObjectType": {
"description": "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.",
"type": "string"
}
},
"required": [
"objectType",
"objectId",
"toObjectType"
],
"type": "object"
}
Implementation Reference
- The main handler function that processes the tool input, constructs the HubSpot CRM v4 API endpoint for listing associations, handles pagination, fetches data using HubSpotClient, and returns the response as JSON or error message.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 schema defining the input parameters for the tool: 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/associations/listAssociationsTool.js:19-43 (registration)ToolDefinition object containing the name 'hubspot-list-associations', detailed description, input schema derived from Zod, and annotations for the tool's behavior.const ToolDefinition = { name: 'hubspot-list-associations', description: ` 🎯 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. `, inputSchema: zodToJsonSchema(AssociationsListSchema), annotations: { title: 'List CRM Object Associations', readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true, }, };
- dist/tools/toolsRegistry.js:32-32 (registration)Instantiation and registration of the AssociationsListTool in the central tools registry.registerTool(new AssociationsListTool());