hubspot-batch-create-associations
Create batch associations between HubSpot objects to link records across different object types. Define association types and specify relationships in a single operation for efficient CRM data management.
Instructions
🛡️ Guardrails:
1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM.
🎯 Purpose:
1. Establishes relationships between HubSpot objects, linking records across different object types, by creating associations between objects in batch.
2. Uses a single set of association types for all associations in the batch.
📋 Prerequisites:
1. Use the hubspot-get-user-details tool to get the OwnerId and UserId if you don't have that already.
2. Use the hubspot-get-association-definitions tool to identify valid association types before creating associations.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fromObjectType | Yes | The type of HubSpot object to create association 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. | |
| inputs | Yes | List of association inputs defining the relationships to create. (max 100 associations per batch) | |
| toObjectType | Yes | The type of HubSpot object to create association 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. | |
| types | Yes | The types of associations to create |
Input Schema (JSON Schema)
{
"$schema": "http://json-schema.org/draft-07/schema#",
"additionalProperties": false,
"properties": {
"fromObjectType": {
"description": "The type of HubSpot object to create association 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"
},
"inputs": {
"description": "List of association inputs defining the relationships to create. (max 100 associations per batch)",
"items": {
"additionalProperties": false,
"properties": {
"from": {
"additionalProperties": false,
"properties": {
"id": {
"description": "The ID of the object to create association from",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
},
"to": {
"additionalProperties": false,
"properties": {
"id": {
"description": "The ID of the object to create association to",
"type": "string"
}
},
"required": [
"id"
],
"type": "object"
}
},
"required": [
"from",
"to"
],
"type": "object"
},
"minItems": 1,
"type": "array"
},
"toObjectType": {
"description": "The type of HubSpot object to create association 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"
},
"types": {
"description": "The types of associations to create",
"items": {
"additionalProperties": false,
"properties": {
"associationCategory": {
"enum": [
"HUBSPOT_DEFINED",
"USER_DEFINED",
"INTEGRATOR_DEFINED"
],
"type": "string"
},
"associationTypeId": {
"exclusiveMinimum": 0,
"type": "integer"
}
},
"required": [
"associationCategory",
"associationTypeId"
],
"type": "object"
},
"minItems": 1,
"type": "array"
}
},
"required": [
"fromObjectType",
"toObjectType",
"types",
"inputs"
],
"type": "object"
}
Implementation Reference
- The BatchCreateAssociationsTool class extends BaseTool and implements the core logic in the async process method. It maps inputs with types and sends a POST request to HubSpot's /crm/v4/associations/{from}/{to}/batch/create endpoint.export class BatchCreateAssociationsTool extends BaseTool { client; constructor() { super(ObjectAssociationSchema, ToolDefinition); this.client = new HubSpotClient(); } async process(args) { try { // Add types to each input const inputs = args.inputs.map(input => ({ ...input, types: args.types, })); const response = await this.client.post(`/crm/v4/associations/${args.fromObjectType}/${args.toObjectType}/batch/create`, { body: { inputs }, }); return { content: [ { type: 'text', text: JSON.stringify(response, null, 2), }, ], }; } catch (error) { return { content: [ { type: 'text', text: `Error creating HubSpot associations: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; } } }
- Zod schemas defining the input parameters for the tool: AssociationTypeSchema (association category and type ID), AssociationInputSchema (from/to object IDs), and ObjectAssociationSchema (combining object types, association types, and batch inputs).const AssociationTypeSchema = z.object({ associationCategory: z.enum(['HUBSPOT_DEFINED', 'USER_DEFINED', 'INTEGRATOR_DEFINED']), associationTypeId: z.number().int().positive(), }); const AssociationInputSchema = z.object({ from: z.object({ id: z.string().describe('The ID of the object to create association from'), }), to: z.object({ id: z.string().describe('The ID of the object to create association to'), }), }); const ObjectAssociationSchema = z.object({ fromObjectType: z .string() .describe(`The type of HubSpot object to create association from. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`), toObjectType: z .string() .describe(`The type of HubSpot object to create association to. Valid values include: ${HUBSPOT_OBJECT_TYPES.join(', ')}. For custom objects, use the hubspot-get-schemas tool to get the objectType.`), types: z.array(AssociationTypeSchema).min(1).describe('The types of associations to create'), inputs: z .array(AssociationInputSchema) .min(1) .describe('List of association inputs defining the relationships to create. (max 100 associations per batch)'), });
- dist/tools/associations/batchCreateAssociationsTool.js:31-53 (registration)ToolDefinition object that registers the tool with its name, detailed description including guardrails and prerequisites, JSON schema from Zod, and annotations for UI hints.const ToolDefinition = { name: 'hubspot-batch-create-associations', description: ` 🛡️ Guardrails: 1. Data Modification Warning: This tool modifies HubSpot data. Only use when the user has explicitly requested to update their CRM. 🎯 Purpose: 1. Establishes relationships between HubSpot objects, linking records across different object types, by creating associations between objects in batch. 2. Uses a single set of association types for all associations in the batch. 📋 Prerequisites: 1. Use the hubspot-get-user-details tool to get the OwnerId and UserId if you don't have that already. 2. Use the hubspot-get-association-definitions tool to identify valid association types before creating associations. `, inputSchema: zodToJsonSchema(ObjectAssociationSchema), annotations: { title: 'Create CRM Object Associations in Batch', readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, };
- dist/tools/toolsRegistry.js:30-30 (registration)Explicit registration of a new instance of BatchCreateAssociationsTool in the central tools registry.registerTool(new BatchCreateAssociationsTool());
- dist/tools/toolsRegistry.js:7-7 (registration)Import of the BatchCreateAssociationsTool class required for registration.import { BatchCreateAssociationsTool } from './associations/batchCreateAssociationsTool.js';