beam-ai-team/hubspot-crm

HubSpot CRM

Unified reference for all HubSpot CRM operations. All scripts live in hubspot-master/scripts/.

Safety Contract

Before creating/updating/archiving contacts, companies, deals, engagements, or associations, show the portal/account, target records or matching criteria, payload summary, association changes, and expected side effects. Require explicit user approval in the current turn before mutating HubSpot records or writing files. Listing and searching records with an approved scope do not require additional approval.

Replaces: hubspot-list-contacts, hubspot-create-contact, hubspot-update-contact, hubspot-search-contacts, hubspot-list-companies, hubspot-create-company, hubspot-search-companies, hubspot-list-deals, hubspot-create-deal, hubspot-update-deal, hubspot-search-deals, hubspot-create-deal-from-transcript, hubspot-list-emails, hubspot-log-email, hubspot-list-calls, hubspot-log-call, hubspot-list-notes, hubspot-create-note, hubspot-list-meetings, hubspot-create-meeting, hubspot-get-associations.

Contacts

# List contacts (paginated)
uv run python hubspot-master/scripts/list_contacts.py --limit 20
uv run python hubspot-master/scripts/list_contacts.py --limit 50 --properties email,firstname,lastname,company

# Create contact
uv run python hubspot-master/scripts/create_contact.py --email "[email protected]" --firstname Jane --lastname Doe --company "Acme"

# Update contact
uv run python hubspot-master/scripts/update_contact.py --id 12345 --email "[email protected]" --company "NewCorp"

# Search contacts
uv run python hubspot-master/scripts/search_contacts.py --email "[email protected]"
uv run python hubspot-master/scripts/search_contacts.py --name "Jane Doe"
uv run python hubspot-master/scripts/search_contacts.py --company "Acme" --limit 10

Companies

# List companies
uv run python hubspot-master/scripts/list_companies.py --limit 20

# Create company
uv run python hubspot-master/scripts/create_company.py --name "Acme Corp" --domain "acme.com" --industry "Technology"

# Search companies
uv run python hubspot-master/scripts/search_companies.py --name "Acme"
uv run python hubspot-master/scripts/search_companies.py --domain "acme.com"

Deals

# List deals
uv run python hubspot-master/scripts/list_deals.py --limit 20

# Create deal
uv run python hubspot-master/scripts/create_deal.py --name "Enterprise License" --amount 50000 --stage "appointmentscheduled"

# Update deal
uv run python hubspot-master/scripts/update_deal.py --id 67890 --stage "closedwon" --amount 55000

# Search deals
uv run python hubspot-master/scripts/search_deals.py --name "Enterprise"
uv run python hubspot-master/scripts/search_deals.py --stage "closedwon" --min-amount 10000

Create deal from transcript

Workflow (no dedicated script — compose from existing scripts):

1. Search for contact/company from transcript participants
2. Create deal with extracted details (name, value, stage)
3. Associate deal with contact and company via create_association.py (default label)

Delete (archive)

Deletes use CRM v3 archive-by-default. Always require explicit confirmation before running.

uv run python hubspot-master/scripts/delete_crm_object.py --object-type contacts --id 12345 --yes
uv run python hubspot-master/scripts/delete_crm_object.py --object-type deals --id 67890 --yes --json

Engagements

Emails

uv run python hubspot-master/scripts/list_emails.py --limit 20
uv run python hubspot-master/scripts/log_email.py --subject "Follow-up" --body "Thanks for the meeting" --direction EMAIL

Calls

uv run python hubspot-master/scripts/list_calls.py --limit 20
uv run python hubspot-master/scripts/log_call.py --title "Discovery call" --body "Discussed pricing" --duration 30

Notes

uv run python hubspot-master/scripts/list_notes.py --limit 20
uv run python hubspot-master/scripts/create_note.py --body "Key decision: proceeding with Enterprise plan"

Meetings

uv run python hubspot-master/scripts/list_meetings.py --limit 20
uv run python hubspot-master/scripts/create_meeting.py --title "Quarterly review" --start "2026-04-01T10:00:00Z" --end "2026-04-01T11:00:00Z"

Associations

# Get records associated with an object
uv run python hubspot-master/scripts/get_associations.py --object-type contacts --object-id 12345 --to-type deals
uv run python hubspot-master/scripts/get_associations.py --object-type deals --object-id 67890 --to-type companies

# Create default association (v4 batch — primary/generic label for the object pair)
uv run python hubspot-master/scripts/create_association.py --from-type contacts --from-id 12345 --to-type companies --to-id 67890
uv run python hubspot-master/scripts/create_association.py --from-type deals --from-id 111 --to-type contacts --to-id 222 --json

API Reference

All endpoints use https://api.hubapi.com with Bearer token auth.

| Resource | Operation | Method | Endpoint | |----------|-----------|--------|----------| | Contacts | list | GET | /crm/v3/objects/contacts | | Contacts | create | POST | /crm/v3/objects/contacts | | Contacts | update | PATCH | /crm/v3/objects/contacts/{id} | | Contacts | search | POST | /crm/v3/objects/contacts/search | | Companies | list | GET | /crm/v3/objects/companies | | Companies | create | POST | /crm/v3/objects/companies | | Companies | search | POST | /crm/v3/objects/companies/search | | Deals | list | GET | /crm/v3/objects/deals | | Deals | create | POST | /crm/v3/objects/deals | | Deals | update | PATCH | /crm/v3/objects/deals/{id} | | Deals | search | POST | /crm/v3/objects/deals/search | | Emails | list | GET | /crm/v3/objects/emails | | Emails | log | POST | /crm/v3/objects/emails | | Calls | list | GET | /crm/v3/objects/calls | | Calls | log | POST | /crm/v3/objects/calls | | Notes | list | GET | /crm/v3/objects/notes | | Notes | create | POST | /crm/v3/objects/notes | | Meetings | list | GET | /crm/v3/objects/meetings | | Meetings | create | POST | /crm/v3/objects/meetings | | Associations | get | GET | /crm/v4/objects/{type}/{id}/associations/{toType} | | Associations | create default | POST | /crm/v4/associations/{fromType}/{toType}/batch/associate/default | | Any object | delete (archive) | DELETE | /crm/v3/objects/{objectType}/{objectId} |

Pagination

All list endpoints support cursor-based pagination via --after. The scripts handle paging.next automatically when using --limit.

Search behavior

Search scripts use a smart fallback: when no filters are provided, they fall back to GET on the list endpoint (recent results). When filters are provided, they POST to the /search endpoint with filterGroups.