HubSpot CRM Deals

Setup

• Add a HubSpot private app token (scopes crm.objects.deals.read and crm.objects.deals.write) as the Bearer credential.
• Pin the pipeline and stage ids you use (Settings > Objects > Deals > Pipelines; the default pipeline is default, stages have internal ids like appointmentscheduled, closedwon). Pin properties too, e.g. dealname,amount,dealstage,pipeline,closedate,hubspot_owner_id.

Review the pipeline

1. searchDeals with filterGroups, e.g. open deals closing this month: [{"filters":[{"propertyName":"dealstage","operator":"NOT_IN","values":["closedwon","closedlost"]},{"propertyName":"closedate","operator":"LTE","value":"2026-10-31T23:59:59Z"}]}], plus the properties you need.
2. getDeal with associations=contacts,companies to see who the deal is with.
3. batchReadDeals for up to 100 deal ids at once; listDeals to page through everything (limit max 100, after from paging.next.after).

Create or move a deal

1. Search first so you don't create a duplicate.
2. Show the user the deal name, amount, stage and close date and get confirmation.
3. createDeal with properties (dealname, pipeline, dealstage required in practice; amount, closedate, hubspot_owner_id optional). To link a contact, add associations: [{"to":{"id":"<contactId>"},"types":[{"associationCategory":"HUBSPOT_DEFINED","associationTypeId":3}]}] (use 5 for a company).
4. To move a deal or change its value, confirm, then updateDeal with only the changed properties (e.g. {"dealstage":"closedwon"}).

Good to know

• Creating or changing deals edits customer data: always confirm createDeal and updateDeal first.
• Use internal property names and stage ids, not labels. A dealstage must belong to the deal's pipeline.
• amount is a string number in the account currency; closedate is ISO 8601 or Unix milliseconds.
• searchDeals returns up to 200 per page and at most 10,000 results; results can lag a few seconds behind writes.
• Filters in one group are AND, groups are OR.