Workflood
Data & Associations
6 min readUpdated August 2026

Working with HubSpot Association API v4 in Custom Code

Master the HubSpot Associations v4 API in TypeScript to query, create, and remove multi-object relationships (Contacts, Companies, Deals, Custom Objects).

Table of Contents

Understanding Associations v4 Architecture

HubSpot's **Associations API v4** allows developers to manage complex, multi-labeled relationships between any CRM objects (e.g., distinguishing between a "Billing Contact" vs. an "Executive Sponsor" on a Deal).

In Workflood, you can query and batch-create associations between: - Standard objects: `contacts`, `companies`, `deals`, `tickets` - Marketing objects: `marketing_events`, `lists` - Custom objects: `2-[object_type_id]`

Querying Associated Records

To retrieve all companies associated with a specific Contact ID:

get-associations.ts
// Fetch associated company IDs for a contact
const associations = await hubspot.client.crm.associations.v4.basicApi.getPage(
  'contacts',        // From Object Type
  '12345678',        // From Object ID
  'companies',       // To Object Type
  10                 // Limit (Max 500)
)

const companyIds = associations.results.map((r) => r.toObjectId)
console.log('Associated Company IDs:', companyIds)

Creating Labeled Associations

When creating associations, you specify the **Association Category** (`HUBSPOT_DEFINED` or `USER_DEFINED`) and the **Association Type ID**:

create-association.ts
// Associate a Deal to a Marketing Event for Revenue Attribution
await hubspot.client.crm.associations.v4.basicApi.create(
  'deals',           // From Object Type
  dealId,            // From Object ID
  'marketing_events',// To Object Type
  marketingEventId,  // To Object ID
  [
    {
      associationCategory: 'HUBSPOT_DEFINED',
      associationTypeId: 15 // HubSpot-defined Deal to Event type
    }
  ]
)

Common Association Type IDs Reference

From ObjectTo ObjectCategoryStandard Type ID
**Contact****Company** (Primary)HUBSPOT_DEFINED1
**Company****Contact**HUBSPOT_DEFINED2
**Deal****Contact**HUBSPOT_DEFINED3
**Contact****Deal**HUBSPOT_DEFINED4
**Deal****Company** (Primary)HUBSPOT_DEFINED5
**Company****Marketing Event**HUBSPOT_DEFINED14
**Deal****Marketing Event**HUBSPOT_DEFINED15
Turnkey Recipe Available

Associate Company to Marketing Event on Attendance

When a contact attends a marketing event (webinar, conference), look up their associated company and link the company to the marketing event for account-level event reporting.

Frequently Asked Questions

How do I associate custom objects using Associations v4?

Use the fully qualified custom object name (e.g., "2-1234567") as the object type identifier in the basicApi.getPage and basicApi.create calls.

Previous Guide
Writing Python 3.11 Actions for HubSpot Workflows
Next Guide
Managing Secrets & API Keys Securely with Libsodium Encryption