home / skills / abdullahbeam / nexus-design-abdullah / hubspot-get-associations

hubspot-get-associations skill

safe

/00-system/skills/hubspot/hubspot-get-associations

This skill retrieves HubSpot object associations such as contacts on deals or deals for a contact to streamline CRM insights.

npx playbooks add skill abdullahbeam/nexus-design-abdullah --skill hubspot-get-associations

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.9 KB

---
name: hubspot-get-associations
description: "Get associated records in HubSpot CRM. Load when user says 'get associations', 'linked records', 'contacts on deal', 'company contacts', 'related records', 'who is on this deal'."
---

# Get HubSpot Associations

**Specialized skill** for retrieving associated records between HubSpot CRM objects.

## Pre-Flight Check

Before running, execute config check:
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/check_hubspot_config.py --json
```

If `ai_action` is not `proceed_with_operation`, follow hubspot-connect setup guide.

---

## Usage

### Required Parameters
- `--object-type` - Source object type (contacts, companies, deals)
- `--object-id` - Source object ID
- `--to-type` - Target object type to find associations

### Examples

**Get contacts on a deal:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type deals \
  --object-id 5840795376 \
  --to-type contacts \
  --json
```

**Get contacts at a company:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type companies \
  --object-id 6493611979 \
  --to-type contacts \
  --json
```

**Get deals for a contact:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type contacts \
  --object-id 12345 \
  --to-type deals \
  --json
```

**Get company for a contact:**
```bash
python 00-system/skills/hubspot/hubspot-master/scripts/get_associations.py \
  --object-type contacts \
  --object-id 12345 \
  --to-type companies \
  --json
```

---

## Valid Object Types

| Type | Description |
|------|-------------|
| contacts | Contact records |
| companies | Company records |
| deals | Deal/opportunity records |

---

## Output Format

```json
{
  "results": [
    {
      "toObjectId": 12345,
      "associationTypes": [
        {
          "category": "HUBSPOT_DEFINED",
          "typeId": 3,
          "label": "Deal to Contact"
        }
      ]
    }
  ]
}
```

---

## Display Format

```
Found 3 contacts associated with deal 5840795376:

1. Contact ID: 12345 (Deal to Contact)
2. Contact ID: 12346 (Deal to Contact)
3. Contact ID: 12347 (Deal to Contact)

Use 'search contacts --id 12345' for full details.
```

---

## Common Use Cases

| User Says | Command |
|-----------|---------|
| "Who is on this deal?" | deals → contacts |
| "What company is John at?" | contacts → companies |
| "Show contacts at Acme" | companies → contacts |
| "What deals does John have?" | contacts → deals |

---

## Error Handling

| Error | Solution |
|-------|----------|
| 401 | Invalid token - re-run setup |
| 403 | Missing read scope for object type |
| 404 | Object not found - check ID |
| 429 | Rate limited - wait and retry |

---

## Related Skills

- `hubspot-list-contacts` - Get contact details
- `hubspot-list-companies` - Get company details
- `hubspot-list-deals` - Get deal details

Overview

This skill retrieves associated records between HubSpot CRM objects so you can quickly see linked contacts, companies, or deals. It supports queries like contacts on a deal, deals for a contact, or company for a contact. Results are returned as a structured list of associated object IDs and association metadata for easy consumption.

How this skill works

The skill calls HubSpot's associations API to list associations from a source object type and ID to a target object type. It validates configuration and API credentials before running and returns JSON results with toObjectId and associationTypes. Display-friendly text can be built from the JSON to show counts and quick next-step commands.

When to use it

You need to list contacts linked to a specific deal.
You want to find the company associated with a contact.
You are mapping deals related to a contact or company.
You want a quick association summary to drive follow-up actions.

Best practices

Run an initial config check to confirm credentials and scopes before querying.
Use numeric HubSpot object IDs and the correct object-type (contacts, companies, deals).
Handle API rate limits by backing off on 429 responses and retrying.
Inspect associationTypes in the response to understand relationship labels and categories.
Combine with list/detail skills to fetch full record data after retrieving IDs.

Example use cases

Get contacts on a deal: source deals, target contacts to reach out to stakeholders.
Get company for a contact: confirm account details before a sales call.
Get deals for a contact: review opportunity history for account planning.
Get contacts at a company: assemble an outreach list for account-based campaigns.

FAQ

What object types can I query associations for?

Supported source and target types are contacts, companies, and deals.

What do common errors mean and how do I fix them?

401 means invalid token — re-run authentication. 403 indicates missing read scope for the object type. 404 means the object ID wasn't found. 429 signals rate limiting — wait and retry.