How do I install the Hubspot skill?

Run npx skillmds@latest add shakudo-io/hubspot in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Hubspot skill do?

Complete HubSpot CRM integration via REST API. Use for managing contacts, companies, deals, pipelines, associations, notes, meetings, tasks, and search. Full CRUD operations with verified API patterns. It is listed under Integrations & APIs on SkillMD.

Is Hubspot safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: makes network calls, reads secrets. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Hubspot?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Hubspot free to use?

Yes. Installing skills from SkillMD is free. This skill is licensed under MIT.

Who published Hubspot?

Shakudo-io (@shakudo-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Hubspot by shakudo-io — Agent Skill

Name: Hubspot
Rating: 4.5 (4 reviews)
Author: Shakudo-io

HubSpot CRM Skill

Complete HubSpot CRM REST API integration for Contacts, Companies, Deals, Pipelines, Associations, Engagements (Notes, Meetings, Tasks, Calls), Properties, and Search.

Why This Skill Exists

HubSpot's official MCP is in beta and read-only. This skill provides full CRUD operations via direct REST API calls, giving agents complete control over CRM data.

Quick Start

# Set your Personal Access Key
export HUBSPOT_PAK="pat-na1-your-key-here"

# List contacts
curl -s -X GET "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

# Search for contacts by email domain
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{"filterGroups":[{"filters":[{"propertyName":"email","operator":"CONTAINS_TOKEN","value":"example.com"}]}],"limit":10}' | jq '.'

# Create a contact
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{"properties":{"email":"new@example.com","firstname":"John","lastname":"Doe"}}' | jq '.'

Prerequisites & Authentication

Personal Access Key (PAK)

HubSpot uses Personal Access Keys for API authentication. Get one from: Settings > Integrations > Private Apps > Create private app

export HUBSPOT_PAK="pat-na1-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

Authentication Header

All API calls use Bearer token authentication:

curl -H "Authorization: Bearer $HUBSPOT_PAK" -H "Content-Type: application/json" ...

API Base URL

https://api.hubapi.com

Required Scopes

Different operations require different scopes. Common ones:

Scope	Operations
`crm.objects.contacts.read`	Read contacts
`crm.objects.contacts.write`	Create/update/delete contacts
`crm.objects.companies.read`	Read companies
`crm.objects.companies.write`	Create/update/delete companies
`crm.objects.deals.read`	Read deals
`crm.objects.deals.write`	Create/update/delete deals
`crm.schemas.contacts.read`	Read contact properties
`sales-email-read`	Read email engagements
`crm.objects.owners.read`	Read owners
`tickets`	Read/write tickets

Part 1: Contacts

List Contacts

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/contacts?limit=10" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

With Specific Properties

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/contacts?limit=10&properties=email,firstname,lastname,phone,company,lifecyclestage" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "id": "14401",
      "properties": {
        "email": "john@example.com",
        "firstname": "John",
        "lastname": "Doe",
        "company": "Acme Inc",
        "phone": "(555) 123-4567",
        "lifecyclestage": "lead"
      },
      "createdAt": "2022-02-02T21:53:24.031Z",
      "updatedAt": "2024-10-04T20:29:25.876Z",
      "archived": false
    }
  ],
  "paging": {
    "next": {
      "after": "14452"
    }
  }
}

Get Single Contact

# By ID
curl -s -X GET "https://api.hubapi.com/crm/v3/objects/contacts/14401?properties=email,firstname,lastname,phone,company" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

# By email (use idProperty parameter)
curl -s -X GET "https://api.hubapi.com/crm/v3/objects/contacts/john@example.com?idProperty=email&properties=firstname,lastname,company" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Contact

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "email": "newcontact@example.com",
      "firstname": "Jane",
      "lastname": "Smith",
      "phone": "555-1234",
      "company": "Tech Corp",
      "lifecyclestage": "lead"
    }
  }' | jq '.'

Response:

{
  "id": "196231033608",
  "properties": {
    "email": "newcontact@example.com",
    "firstname": "Jane",
    "lastname": "Smith",
    "lifecyclestage": "lead"
  },
  "createdAt": "2026-01-26T16:38:26.645Z"
}

Update Contact

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/contacts/196231033608" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "company": "New Company Inc",
      "phone": "555-9999",
      "lifecyclestage": "opportunity"
    }
  }' | jq '.'

Delete (Archive) Contact

curl -s -X DELETE "https://api.hubapi.com/crm/v3/objects/contacts/196231033608" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json"
# Returns HTTP 204 No Content on success

Part 2: Companies

List Companies

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/companies?limit=10&properties=name,domain,industry,city,state" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Get Single Company

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/companies/7992218231?properties=name,domain,industry,numberofemployees,annualrevenue" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Company

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/companies" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "name": "New Tech Company",
      "domain": "newtechcompany.com",
      "industry": "Technology",
      "city": "San Francisco",
      "state": "CA",
      "numberofemployees": "50"
    }
  }' | jq '.'

Update Company

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/companies/7992218231" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "numberofemployees": "100",
      "annualrevenue": "5000000"
    }
  }' | jq '.'

Delete Company

curl -s -X DELETE "https://api.hubapi.com/crm/v3/objects/companies/7992218231" \
  -H "Authorization: Bearer $HUBSPOT_PAK"

Part 3: Deals

List Deals

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/deals?limit=10&properties=dealname,amount,dealstage,closedate,pipeline" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "id": "8001924129",
      "properties": {
        "amount": "10000",
        "closedate": "2022-06-11T11:57:20.963Z",
        "dealname": "Enterprise Deal",
        "dealstage": "closedwon",
        "pipeline": "default"
      }
    }
  ]
}

Get Single Deal

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/deals/8001924129?properties=dealname,amount,dealstage,closedate,pipeline,hubspot_owner_id" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Deal

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/deals" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "dealname": "New Enterprise Deal",
      "amount": "50000",
      "dealstage": "appointmentscheduled",
      "pipeline": "default",
      "closedate": "2026-06-30"
    }
  }' | jq '.'

Update Deal (Move Through Pipeline)

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/deals/8001924129" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "dealstage": "qualifiedtobuy",
      "amount": "75000"
    }
  }' | jq '.'

Delete Deal

curl -s -X DELETE "https://api.hubapi.com/crm/v3/objects/deals/8001924129" \
  -H "Authorization: Bearer $HUBSPOT_PAK"

Part 4: Pipelines

List Deal Pipelines

curl -s -X GET "https://api.hubapi.com/crm/v3/pipelines/deals" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response (example):

{
  "results": [
    {
      "id": "default",
      "label": "Sales Pipeline",
      "stages": [
        {"id": "14960226", "label": "Disco 1 - 3/8 MEDDPICC", "displayOrder": 0},
        {"id": "appointmentscheduled", "label": "Disco 2 - 6/8 MEDDPICC", "displayOrder": 1},
        {"id": "qualifiedtobuy", "label": "Disco 3 - 8/8 MEDDPICC", "displayOrder": 2},
        {"id": "contractsent", "label": "Contracting", "displayOrder": 3},
        {"id": "closedwon", "label": "Closed won", "displayOrder": 5},
        {"id": "closedlost", "label": "Closed lost", "displayOrder": 6}
      ]
    }
  ]
}

Get Specific Pipeline

curl -s -X GET "https://api.hubapi.com/crm/v3/pipelines/deals/default" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Part 5: Search

HubSpot's Search API is powerful for filtering CRM objects.

Search Contacts by Email Domain

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "email",
        "operator": "CONTAINS_TOKEN",
        "value": "example.com"
      }]
    }],
    "properties": ["email", "firstname", "lastname", "company"],
    "limit": 20
  }' | jq '.'

Search Companies by Industry

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/companies/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "industry",
        "operator": "EQ",
        "value": "Technology"
      }]
    }],
    "properties": ["name", "domain", "industry", "numberofemployees"],
    "limit": 20
  }' | jq '.'

Search Deals by Stage and Amount

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/deals/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [
        {"propertyName": "dealstage", "operator": "EQ", "value": "qualifiedtobuy"},
        {"propertyName": "amount", "operator": "GTE", "value": "10000"}
      ]
    }],
    "properties": ["dealname", "amount", "dealstage", "closedate"],
    "sorts": [{"propertyName": "amount", "direction": "DESCENDING"}],
    "limit": 20
  }' | jq '.'

Search with OR Logic (Multiple Filter Groups)

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/contacts/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [
      {"filters": [{"propertyName": "lifecyclestage", "operator": "EQ", "value": "lead"}]},
      {"filters": [{"propertyName": "lifecyclestage", "operator": "EQ", "value": "opportunity"}]}
    ],
    "properties": ["email", "firstname", "lastname", "lifecyclestage"],
    "limit": 50
  }' | jq '.'

Search Operators

Operator	Description	Example
`EQ`	Equals	`"value": "lead"`
`NEQ`	Not equals	`"value": "customer"`
`LT`	Less than	`"value": "100"`
`LTE`	Less than or equal	`"value": "100"`
`GT`	Greater than	`"value": "1000"`
`GTE`	Greater than or equal	`"value": "1000"`
`CONTAINS_TOKEN`	Contains (for text/email)	`"value": "example.com"`
`NOT_CONTAINS_TOKEN`	Does not contain	`"value": "spam"`
`HAS_PROPERTY`	Property has any value	(no value needed)
`NOT_HAS_PROPERTY`	Property is empty	(no value needed)
`BETWEEN`	Between two values	`"value": "100", "highValue": "1000"`

Part 6: Associations

Associations link CRM objects together (contacts to companies, deals to contacts, etc.).

Get Associations

# Get companies associated with a contact
curl -s -X GET "https://api.hubapi.com/crm/v4/objects/contacts/14401/associations/companies" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

# Get contacts associated with a deal
curl -s -X GET "https://api.hubapi.com/crm/v4/objects/deals/8001924129/associations/contacts" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "toObjectId": 7993011870,
      "associationTypes": [
        {"category": "HUBSPOT_DEFINED", "typeId": 1, "label": "Primary"}
      ]
    }
  ]
}

Create Association

# Associate contact with company (Primary)
curl -s -X PUT "https://api.hubapi.com/crm/v4/objects/contacts/196246562371/associations/companies/49716553474" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '[{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 1}]' | jq '.'

# Associate deal with contact
curl -s -X PUT "https://api.hubapi.com/crm/v4/objects/deals/8001924129/associations/contacts/14401" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '[{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 3}]' | jq '.'

Common Association Type IDs

From	To	TypeId	Label
Contact	Company	1	Primary
Contact	Company	279	Secondary
Deal	Contact	3	Deal to Contact
Deal	Company	5	Deal to Company
Contact	Deal	4	Contact to Deal

Delete Association

curl -s -X DELETE "https://api.hubapi.com/crm/v4/objects/contacts/14401/associations/companies/7993011870" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json"

Part 7: Engagements (Notes, Meetings, Tasks, Calls)

Notes

List Notes

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/notes?limit=10&properties=hs_note_body,hs_timestamp" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Note

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/notes" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_note_body": "Called customer about renewal. They are interested in upgrading.",
      "hs_timestamp": "2026-01-26T12:00:00.000Z"
    }
  }' | jq '.'

Associate Note with Contact

# First create note, get the ID, then associate
curl -s -X PUT "https://api.hubapi.com/crm/v4/objects/notes/NOTE_ID/associations/contacts/CONTACT_ID" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '[{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 202}]' | jq '.'

Meetings

List Meetings

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/meetings?limit=10&properties=hs_meeting_title,hs_meeting_start_time,hs_meeting_end_time,hs_meeting_outcome" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Meeting

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/meetings" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_meeting_title": "Discovery Call",
      "hs_meeting_start_time": "2026-02-01T14:00:00.000Z",
      "hs_meeting_end_time": "2026-02-01T15:00:00.000Z",
      "hs_meeting_outcome": "SCHEDULED"
    }
  }' | jq '.'

Tasks

List Tasks

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/tasks?limit=10&properties=hs_task_subject,hs_task_status,hs_task_priority,hs_timestamp" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Task

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/tasks" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_task_subject": "Follow up with customer",
      "hs_task_status": "NOT_STARTED",
      "hs_task_priority": "HIGH",
      "hs_timestamp": "2026-02-01T09:00:00.000Z"
    }
  }' | jq '.'

Update Task Status

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/tasks/TASK_ID" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_task_status": "COMPLETED"
    }
  }' | jq '.'

Calls

List Calls

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/calls?limit=10&properties=hs_call_title,hs_call_status,hs_call_duration" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Call Record

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/calls" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_call_title": "Outbound sales call",
      "hs_call_body": "Discussed pricing and next steps",
      "hs_call_status": "COMPLETED",
      "hs_call_duration": "1800000",
      "hs_timestamp": "2026-01-26T10:00:00.000Z"
    }
  }' | jq '.'

Part 8: Owners

Owners are HubSpot users who can be assigned to CRM records.

List Owners

curl -s -X GET "https://api.hubapi.com/crm/v3/owners?limit=10" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "id": "75464028",
      "email": "user@company.com",
      "type": "PERSON",
      "firstName": "John",
      "lastName": "Smith",
      "userId": 75464028,
      "createdAt": "2024-12-17T21:11:20.407Z",
      "teams": [
        {"id": "38063404", "name": "Sales Team", "primary": true}
      ]
    }
  ]
}

Get Single Owner

curl -s -X GET "https://api.hubapi.com/crm/v3/owners/75464028" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Get Owner by Email

curl -s -X GET "https://api.hubapi.com/crm/v3/owners?email=user@company.com" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Part 9: Tickets

List Tickets

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/tickets?limit=10&properties=subject,hs_ticket_priority,hs_pipeline_stage,content" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "id": "2856139557",
      "properties": {
        "subject": "Support Request - Integration Issue",
        "hs_ticket_priority": "HIGH",
        "hs_pipeline_stage": "1"
      }
    }
  ]
}

Create Ticket

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/tickets" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "subject": "Customer Support Request",
      "content": "Customer needs help with API integration",
      "hs_ticket_priority": "HIGH",
      "hs_pipeline_stage": "1"
    }
  }' | jq '.'

Update Ticket

curl -s -X PATCH "https://api.hubapi.com/crm/v3/objects/tickets/TICKET_ID" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "properties": {
      "hs_ticket_priority": "LOW",
      "hs_pipeline_stage": "2"
    }
  }' | jq '.'

Search Tickets

curl -s -X POST "https://api.hubapi.com/crm/v3/objects/tickets/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "hs_ticket_priority",
        "operator": "EQ",
        "value": "HIGH"
      }]
    }],
    "properties": ["subject", "hs_ticket_priority", "hs_pipeline_stage"],
    "limit": 20
  }' | jq '.'

Part 10: Emails

Email engagements track email communications in HubSpot.

List Emails

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/emails?limit=10&properties=hs_email_subject,hs_email_direction,hs_email_status,hs_email_text" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "results": [
    {
      "id": "19331427252",
      "properties": {
        "hs_email_direction": "EMAIL",
        "hs_email_status": "SENT",
        "hs_email_subject": "Re: Follow up on our meeting"
      }
    }
  ]
}

Email Direction Values

Value	Description
`EMAIL`	Outbound email sent
`INCOMING_EMAIL`	Inbound email received
`FORWARDED_EMAIL`	Forwarded email

Get Single Email

curl -s -X GET "https://api.hubapi.com/crm/v3/objects/emails/19331427252?properties=hs_email_subject,hs_email_text,hs_email_html,hs_email_direction" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Search Emails

# Find emails by subject
curl -s -X POST "https://api.hubapi.com/crm/v3/objects/emails/search" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "filterGroups": [{
      "filters": [{
        "propertyName": "hs_email_subject",
        "operator": "CONTAINS_TOKEN",
        "value": "meeting"
      }]
    }],
    "properties": ["hs_email_subject", "hs_email_direction", "hs_email_status"],
    "limit": 20
  }' | jq '.'

Get Emails for a Contact

# First get associations, then fetch emails
curl -s -X GET "https://api.hubapi.com/crm/v4/objects/contacts/CONTACT_ID/associations/emails" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Part 11: Properties

List Properties for Object Type

# Contact properties
curl -s -X GET "https://api.hubapi.com/crm/v3/properties/contacts" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.results | length'

# Company properties
curl -s -X GET "https://api.hubapi.com/crm/v3/properties/companies" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.results[:5]'

# Deal properties
curl -s -X GET "https://api.hubapi.com/crm/v3/properties/deals" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.results | map(.name)'

Get Single Property

curl -s -X GET "https://api.hubapi.com/crm/v3/properties/contacts/email" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Create Custom Property

curl -s -X POST "https://api.hubapi.com/crm/v3/properties/contacts" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "customer_tier",
    "label": "Customer Tier",
    "type": "enumeration",
    "fieldType": "select",
    "groupName": "contactinformation",
    "options": [
      {"label": "Bronze", "value": "bronze", "displayOrder": 1},
      {"label": "Silver", "value": "silver", "displayOrder": 2},
      {"label": "Gold", "value": "gold", "displayOrder": 3}
    ]
  }' | jq '.'

Part 12: Account Info

Get Account Details

curl -s -X GET "https://api.hubapi.com/account-info/v3/details" \
  -H "Authorization: Bearer $HUBSPOT_PAK" \
  -H "Content-Type: application/json" | jq '.'

Response:

{
  "portalId": 21367798,
  "accountType": "STANDARD",
  "timeZone": "US/Eastern",
  "companyCurrency": "USD",
  "uiDomain": "app.hubspot.com"
}

Quick Reference

Endpoints Summary

Action	Method	Endpoint
List objects	GET	`/crm/v3/objects/{objectType}`
Get object	GET	`/crm/v3/objects/{objectType}/{id}`
Create object	POST	`/crm/v3/objects/{objectType}`
Update object	PATCH	`/crm/v3/objects/{objectType}/{id}`
Delete object	DELETE	`/crm/v3/objects/{objectType}/{id}`
Search	POST	`/crm/v3/objects/{objectType}/search`
Get associations	GET	`/crm/v4/objects/{fromType}/{id}/associations/{toType}`
Create association	PUT	`/crm/v4/objects/{fromType}/{id}/associations/{toType}/{toId}`
List pipelines	GET	`/crm/v3/pipelines/{objectType}`
List properties	GET	`/crm/v3/properties/{objectType}`
List owners	GET	`/crm/v3/owners`
Account info	GET	`/account-info/v3/details`

Object Types

Object	objectType value
Contacts	`contacts`
Companies	`companies`
Deals	`deals`
Tickets	`tickets`
Notes	`notes`
Meetings	`meetings`
Tasks	`tasks`
Calls	`calls`
Emails	`emails`

Pagination

All list endpoints support pagination:

curl "https://api.hubapi.com/crm/v3/objects/contacts?limit=100&after=14452" \
  -H "Authorization: Bearer $HUBSPOT_PAK"

limit: Max 100 per request
after: Cursor from previous response's paging.next.after

Rate Limits

Standard: 100 requests per 10 seconds
Daily: Based on subscription tier (typically 500k/day for Pro)
Search: 4 requests per second

When rate limited, response includes:

{
  "status": "error",
  "message": "You have reached your secondly limit.",
  "category": "RATE_LIMITS"
}

Error Handling

HTTP Code	Meaning	Action
200/201	Success	Parse response
204	Success (no content)	Delete succeeded
400	Bad request	Check request body/params
401	Unauthorized	Check PAK token
403	Forbidden	Missing required scope
404	Not found	Object doesn't exist
409	Conflict	Duplicate (e.g., email exists)
429	Rate limited	Wait and retry

Common Error Response

{
  "status": "error",
  "message": "This app hasn't been granted all required scopes",
  "category": "MISSING_SCOPES",
  "errors": [{
    "message": "One or more of the following scopes are required.",
    "context": {
      "requiredGranularScopes": ["crm.objects.owners.read"]
    }
  }]
}

Hubspot

File contents

HubSpot CRM Skill

Why This Skill Exists

Quick Start

Prerequisites & Authentication

Personal Access Key (PAK)

Authentication Header

API Base URL

Required Scopes

Part 1: Contacts

List Contacts

With Specific Properties

Get Single Contact

Create Contact

Update Contact

Delete (Archive) Contact

Part 2: Companies

List Companies

Get Single Company

Create Company

Update Company

Delete Company

Part 3: Deals

List Deals

Get Single Deal

Create Deal

Update Deal (Move Through Pipeline)

Delete Deal

Part 4: Pipelines

List Deal Pipelines

Get Specific Pipeline

Part 5: Search

Search Contacts by Email Domain

Search Companies by Industry

Search Deals by Stage and Amount

Search with OR Logic (Multiple Filter Groups)

Search Operators

Part 6: Associations

Get Associations

Create Association

Common Association Type IDs

Delete Association

Part 7: Engagements (Notes, Meetings, Tasks, Calls)

Notes

List Notes

Create Note

Associate Note with Contact

Meetings

List Meetings

Create Meeting

Tasks

List Tasks

Create Task

Update Task Status

Calls

List Calls

Create Call Record

Part 8: Owners

List Owners

Get Single Owner

Get Owner by Email

Part 9: Tickets

List Tickets

Create Ticket

Update Ticket

Search Tickets

Part 10: Emails

List Emails

Email Direction Values

Get Single Email

Search Emails

Get Emails for a Contact

Part 11: Properties

List Properties for Object Type

Get Single Property

Create Custom Property

Part 12: Account Info

Get Account Details

Quick Reference