HubSpot Lists API validation patterns and common error prevention. Use when creating or updating lists, filtering contacts, validating property rules, handling list membership criteria, or troubleshooting Lists API errors. Provides error taxonomy, filter syntax reference, and proven solutions.
From opspal-hubspotnpx claudepluginhub revpalsfdc/opspal-commercial --plugin opspal-hubspotThis skill is limited to using the following tools:
filter-patterns.mdimport-validation.mdlist-membership.mdproperty-rules.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
| Error | Cause | Solution |
|---|---|---|
| Wrong Association ID | Using 280 instead of 279 | Use CONTACT_TO_COMPANY: 279 |
| Invalid Operator | Using >= instead of enum | Use IS_GREATER_THAN_OR_EQUAL_TO |
| Missing operationType | Omitting required field | Always include "operationType": "UNIFIED_EVENTS" |
| Invalid Filter Structure | Wrong nesting | Use OR-with-nested-AND pattern |
{
"filterBranch": {
"filterBranchType": "OR",
"filterBranches": [
{
"filterBranchType": "AND",
"filterBranches": [],
"filters": [/* your filters here */]
}
]
}
}
# Validate list definition before API call
node scripts/lib/hubspot-list-validator.js validate <list-json>
# Test filter syntax
node scripts/lib/hubspot-filter-tester.js test <filter-json>
See supporting files:
property-rules.md - Property validation requirementslist-membership.md - List criteria patternsfilter-patterns.md - Filter syntax referenceimport-validation.md - Batch import rules