Connection
- Authentication: API key (Private App access token).
HubSpot → Settings → Integrations → Private Apps (Legacy apps) → Create a private app. Grant the scopes of the tools you will give your agents: CRM objects “crm.objects.<type>.read/write” (contacts, companies, deals, tickets, leads, line_items, products, quotes, custom…), “crm.objects.owners.read”, “crm.schemas.<type>.read/write” (properties, pipelines, custom object schemas), “crm.lists.read/write”, “crm.import”, “crm.export”, “settings.users.read” and “settings.users.teams.read”; for marketing: “content” and “marketing-email” (marketing emails), “transactional-email”, “forms”, “marketing.campaigns.read/write”, “communication_preferences.read_write”; for sales and service: “automation” and “automation.sequences.enrollments.write” (workflows, sequences), “conversations.read/write”, “scheduler.meetings.meeting-link.read”, “files.read”. A missing scope makes only the related tools fail with 403. Then copy the access token (starts with pat-).See HubSpot’s documentation.
Read actions (89)
| Action | Description |
|---|---|
batch_read_associations | Batch read the associations of up to 100 source records towards a target object type. |
batch_read_objects | Batch read up to 100 records of one object type by id (or by a unique property via idProperty). |
get_account_details | Fetch the HubSpot account details (portal id, timezone, currency, data hosting location). |
get_call | Fetch one logged call by id, with optional properties and associations. |
get_campaign | Fetch a campaign (properties and, with dates, its asset metrics). |
get_campaign_metrics | Aggregated metrics of a campaign (sessions, new contacts, influenced contacts…). |
get_company | Fetch a single CRM company by id. |
get_contact | Fetch a single CRM contact by id. |
get_deal | Fetch a single CRM deal by id. |
get_export_status | Fetch the status (and download URL once COMPLETE) of an export started with start_export. |
get_file | Fetch a file’s metadata (name, size, type, public URL if any). |
get_file_signed_url | Get a temporary signed download URL for a file (also works for private files). |
get_form | Fetch a form definition (fields, groups, settings) by id (the form GUID). |
get_import | Fetch the status of one CRM import job. |
get_import_errors | List the row errors of one CRM import job. |
get_list | Fetch one CRM list by id. |
get_list_by_name | Fetch one CRM list by its exact name and object type. |
get_list_memberships | List the record ids that belong to a CRM list (paged). |
get_marketing_email | Fetch a single marketing email by id. |
get_marketing_email_draft | Fetch the draft version of a marketing email (the unpublished edits, if any). |
get_marketing_email_statistics | Aggregated e-mail performance (sent, delivered, opens, clicks, bounces, unsubscribes…) over a period, optionally for given emails. Use get_marketing_email_statistics_histogram for a time series. |
get_marketing_email_statistics_histogram | E-mail performance as a time series (one bucket per interval) over a period, optionally for given emails. |
get_meeting | Fetch one logged meeting by id, with optional properties and associations. |
get_meeting_link_availability | Available meeting slots of a meeting link for the coming months, plus the link’s booking form fields and allowed durations. |
get_note | Fetch one CRM note by id, with optional properties and associations. |
get_object | Fetch one record of any CRM object type by id (or by a unique property via idProperty), with optional properties and associations. |
get_owner | Fetch a single CRM owner by id. |
get_pipeline | Fetch one pipeline with its stages. |
get_property | Fetch one property definition (type, options, group) by internal name. |
get_quote | Fetch one quote by id, with optional properties and associations. |
get_record_list_memberships | List the CRM lists a given record belongs to. |
get_schema | Fetch one custom object schema by object type id (2-123456) or fully qualified name (p_name). |
get_sequence | Fetch a sequence and its steps. Requires Sales/Service Hub Professional or higher. |
get_sequence_enrollment | Check whether a contact is currently enrolled in a sequence (and which one). Requires Sales/Service Hub Professional or higher. |
get_subscription_statuses | Subscription status of one e-mail address for every subscription type (SUBSCRIBED / NOT_SUBSCRIBED, with legal basis). |
get_task | Fetch a single CRM task by id. |
get_thread | Fetch one conversation thread (status, inbox, assignee, associated contact). |
get_ticket | Fetch a single support ticket by id. |
get_user | Fetch one HubSpot user by id (or by email with idProperty EMAIL). |
get_workflow | Fetch a workflow definition (enrollment criteria, actions). Read-only. |
list_association_labels | List the association labels (and their type ids) defined between two object types. |
list_associations | List the records of a target type associated with one record, with their association labels. |
list_calls | List logged calls (paged). Use list_properties (objectType calls) to discover property names to request. |
list_campaign_assets | List the assets of one type attached to a campaign (e.g. its marketing emails or forms). |
list_campaigns | List marketing campaigns (paged). Requires Marketing Hub Professional or higher and the “marketing.campaigns.read” scope. |
list_companies | List CRM companies (paged). |
list_contacts | List CRM contacts (paged). |
list_conversation_channels | List the conversation channels (e-mail, live chat, Facebook Messenger, forms, custom…) with their ids. |
list_deals | List CRM deals (paged). |
list_email_engagements | List emails logged on CRM records (paged). Use list_properties (objectType emails) to discover property names to request. |
list_form_submissions | List the submissions received by a form (newest first), with the submitted field values. Contains personal data. Requires the “forms” scope. |
list_forms | List HubSpot forms (paged). Requires the “forms” scope. |
list_imports | List the CRM import jobs (paged). |
list_inboxes | List the conversation inboxes of the portal (id and name). Requires the “conversations.read” scope and Sales/Service Hub. |
list_leads | List leads (paged). Use list_properties (objectType leads) to discover property names to request. |
list_line_items | List line items (paged). Use list_properties (objectType line_items) to discover property names to request. |
list_marketing_email_revisions | List the revision history of a marketing email. |
list_marketing_emails | List marketing emails (paged), newest first by default. Requires the “content” scope and Marketing Hub. Use includeStats for send/open/click counts. |
list_meeting_links | List the portal’s meeting scheduling links (slug, name, organizer). Requires the “scheduler.meetings.meeting-link.read” scope. |
list_meetings | List logged meetings (paged). Use list_properties (objectType meetings) to discover property names to request. |
list_notes | List CRM notes (paged). Use list_properties (objectType notes) to discover property names to request. |
list_objects | List records of any CRM object type (standard or custom), paged. |
list_owners | List CRM owners (users records can be assigned to), optionally filtered by email. |
list_pipeline_stages | List the stages of a pipeline. |
list_pipelines | List pipelines and their stages for deals or tickets. |
list_products | List products (paged). Use list_properties (objectType products) to discover property names to request. |
list_properties | List all property definitions (internal name, label, type, options) of an object type. Call this before writing properties. |
list_property_groups | List the property groups of an object type. |
list_quotes | List quotes (paged). Use list_properties (objectType quotes) to discover property names to request. |
list_roles | List the user roles of the HubSpot account. |
list_schemas | List the custom object schemas of the account (object type id, properties, associations). |
list_sequences | List the sales sequences of one HubSpot user. Requires Sales Hub or Service Hub Professional/Enterprise (403 otherwise) and the “automation.sequences.read” scope. |
list_subscription_types | List the portal’s e-mail subscription types (id, name, description). Use these ids as subscriptionId in subscribe_contact / unsubscribe_contact. Requires the “communication_preferences.read” scope. |
list_tasks | List CRM tasks (paged). Use list_properties (objectType tasks) to discover property names to request. |
list_teams | List the teams of the HubSpot account. |
list_thread_messages | List the messages and internal comments of a thread (the conversation content: personal data). |
list_threads | List conversation threads, optionally filtered by status, inbox or contact. Contains customer messages metadata. |
list_tickets | List support tickets (paged). |
list_users | List the HubSpot users of the account (id, email, role, team). |
list_workflows | List automation workflows (id, name, type, enabled). Requires Marketing/Sales/Service Hub Professional or higher and the “automation” scope. |
search_companies | Search CRM companies by text query and/or property filters. |
search_contacts | Search CRM contacts by text query and/or property filters. |
search_deals | Search CRM deals by text query and/or property filters. |
search_files | Search the HubSpot file manager by name, type, extension or folder. Requires the “files” scope. |
search_lists | Search CRM lists by name and/or object type (read-only query). |
search_notes | Search CRM notes by free text and/or property filters (read-only query). |
search_objects | Search records of any CRM object type by free text and/or property filters (read-only query). |
search_tasks | Search CRM tasks by free text and/or property filters (read-only query). |
search_tickets | Search support tickets by text query and/or property filters. |
Write actions (81)
| Action | Description |
|---|---|
add_to_list | Add records to a MANUAL or SNAPSHOT list by record id. |
archive_form | Archive (delete) a form. Existing submissions are kept. |
archive_object | Archive (soft-delete) a record of any CRM object type. |
archive_property | Archive a custom property (data of the property is no longer usable). |
archive_property_group | Archive an empty property group. |
archive_thread | Archive a conversation thread (moves it to the trash, restorable with update_thread restoreArchived). Prefer update_thread status CLOSED. |
associate_campaign_asset | Attach an existing asset (email, form, landing page…) to a campaign. |
batch_archive_associations | Batch remove ALL associations between up to 100 source records and given target records. |
batch_archive_objects | Batch archive (soft-delete) up to 100 records of one object type by id. |
batch_create_associations | Batch associate up to 100 record pairs of the same two object types, each with explicit association type(s). |
batch_create_objects | Batch create up to 100 records of one object type. Use list_properties first to discover valid property names. |
batch_update_objects | Batch update up to 100 records of one object type. Use list_properties first to discover valid property names. |
batch_upsert_objects | Batch create-or-update up to 100 records of one object type, matched on a unique property (idProperty). Use list_properties first to discover valid property names. |
book_meeting | Book a meeting through a meeting link on behalf of a prospect (creates a meeting and a contact if needed, and sends invitations). Pick the start time from get_meeting_link_availability. |
cancel_import | Cancel a running CRM import job. |
clone_marketing_email | Duplicate a marketing email into a new draft. Returns the new email (use its id afterwards). |
create_association | Associate two CRM records with the default association type (e.g. contact ↔ company). |
create_association_label | Create a custom association label between two object types. |
create_call | Log a call on CRM records (hs_call_title, hs_call_body, hs_timestamp, hs_call_direction, hs_call_duration, hs_call_status). Pass associations to attach it to a contact, company or deal. |
create_campaign | Create a marketing campaign. Returns its id (campaignGuid) for associate_campaign_asset. |
create_company | Create a CRM company. |
create_contact | Create a CRM contact. |
create_deal | Create a CRM deal. |
create_email_engagement | Log an email on CRM records (does NOT send anything). Pass associations to attach it to a contact, company or deal. |
create_form | Create a HubSpot form. Provide name and fieldGroups (formType defaults to “hubspot”); configuration, displayOptions, legalConsentOptions, createdAt and each field’s validation get working defaults when omitted. |
create_labeled_association | Associate two records with explicit association type(s)/label(s) (e.g. a custom label like “Decision maker”). Use list_association_labels to find the type ids. |
create_lead | Create a lead. A lead must be associated with a contact (associations, lead→contact type 578). Use list_properties (objectType leads) first to discover valid property names. |
create_line_item | Create a line item. Common properties: name, quantity, price, hs_product_id. Associate it to a deal (line_item→deal type 20). Use list_properties (objectType line_items) first to discover valid property names. |
create_list | Create a CRM list: MANUAL (static, fill with add_to_list), DYNAMIC or SNAPSHOT (need a filterBranch). |
create_marketing_email | Create a draft marketing email. |
create_meeting | Log a meeting on CRM records (title, notes, start/end time, outcome). Pass associations to attach it to a contact, company or deal. |
create_note | Log a note in the CRM. Pass associations to attach it to a contact, company or deal (note→contact type 202), or attach it later with create_association. |
create_object | Create a record of any CRM object type, optionally associated to other records. Use list_properties first to discover valid property names. |
create_pipeline | Create a pipeline with its initial stages. |
create_pipeline_stage | Add a stage to a pipeline. |
create_product | Create a product. Common properties: name, price, description, hs_sku. Use list_properties (objectType products) first to discover valid property names. |
create_property | Create a custom CRM property on an object type. |
create_property_group | Create a property group on an object type. |
create_task | Create a CRM task (to-do, call or email follow-up). Pass associations to attach it to a contact, company or deal (task→contact type 204). |
create_ticket | Create a support ticket. |
delete_association | Remove ALL associations (every label) between two records. |
delete_association_label | Delete a custom association label. |
delete_company | Archive (delete) a CRM company. |
delete_contact | Archive (delete) a CRM contact. |
delete_deal | Archive (delete) a CRM deal. |
delete_list | Delete a CRM list (recoverable for 90 days in HubSpot). |
delete_marketing_email | Delete a marketing email. |
delete_note | Archive (delete) a CRM note. |
delete_pipeline | Delete a pipeline. Fails while records still use it unless validateReferencesBeforeDelete is false. |
delete_pipeline_stage | Delete a pipeline stage (must hold no records). |
delete_task | Archive (delete) a CRM task. |
delete_ticket | Archive (delete) a support ticket. |
enroll_in_sequence | Enroll a contact in a sequence: HubSpot will then send the sequence’s e-mails/tasks on the user’s behalf. Requires Sales/Service Hub Professional or higher, a connected inbox for the sender and the “automation.sequences.enrollments.write” scope. |
gdpr_delete_contact | Permanently delete a contact and its personal data (GDPR erasure). Irreversible. |
merge_objects | Merge two records of the same type (contacts, companies, deals, tickets…): objectIdToMerge is folded into primaryObjectId. Irreversible. |
publish_marketing_email | Publish (or send, if scheduled/automated) a marketing email. This can send real e-mails to contacts: only call when explicitly asked. Requires Marketing Hub Professional or higher. |
remove_from_list | Remove records from a MANUAL or SNAPSHOT list by record id. |
send_thread_message | Reply in a conversation thread (type MESSAGE: sent to the customer) or add an internal note (type COMMENT: visible to the team only). Replies are delivered to the customer: only send when asked. To reply, read the thread first for channelId, channelAccountId and recipients. |
send_transactional_email | Send a transactional e-mail from a pre-built HubSpot transactional template (single send). Requires the Transactional Email add-on (otherwise 403) and the “transactional-email” scope. The template (emailId) must already exist and be published. |
start_export | Start an asynchronous CRM export (CSV/XLSX) of a list or a view; poll get_export_status for the download URL. Use list_properties first to discover property names. |
subscribe_contact | Subscribe (or re-subscribe) an e-mail address to one subscription type. Only do it with the person’s consent: the legal basis is recorded in HubSpot. Requires the “communication_preferences.write” scope. |
unpublish_marketing_email | Unpublish a marketing email (back to draft / cancel a scheduled send). Requires Marketing Hub Professional or higher. |
unsubscribe_contact | Unsubscribe an e-mail address from one subscription type (it will stop receiving those marketing e-mails). |
update_association_label | Rename a custom association label. |
update_campaign | Update campaign properties. Send only what changes. |
update_company | Update properties of a CRM company. |
update_contact | Update properties of a CRM contact. |
update_deal | Update properties of a CRM deal (e.g. move stage, change amount). |
update_form | Partially update a form (name, fields, settings). Send only the fields to change. |
update_list_name | Rename a CRM list. |
update_marketing_email | Update a marketing email (name, subject, or any other email field). Edits the live version; for a published email prefer update_marketing_email_draft then publish_marketing_email. |
update_marketing_email_draft | Update the draft version of a marketing email without touching the published one. Publish afterwards with publish_marketing_email. |
update_note | Update a CRM note (hs_note_body, hs_timestamp). |
update_object | Update properties of a record of any CRM object type. Use list_properties first to discover valid property names. |
update_pipeline | Update a pipeline label or display order. |
update_pipeline_stage | Update a pipeline stage (label, order, probability/ticket state). |
update_property | Update a custom property definition (label, description, group, options, visibility). |
update_property_group | Update a property group label or display order. |
update_task | Update properties of a CRM task (e.g. mark hs_task_status COMPLETED). |
update_thread | Open or close a conversation thread, or restore an archived one (restoreArchived). |
update_ticket | Update properties of a support ticket (e.g. change stage or priority). |
Permissions
Every action above must be explicitly granted to an agent before it can be used. See Permissions for the grant model and Security for how credentials are protected.Last reviewed against the provider API: July 2026.