Short answer. Create a HubSpot app with OAuth and CRM scopes, read contact and deal properties by internal name, enrich only empty or AI-owned fields, score with a structured-output prompt, and draft sequences for a human to send. Check consent before any marketing action and log every write with its source and approval.
1. Scope the agent to enrichment and drafting
HubSpot already has workflows, sequences and automation. The agent should add judgment where rules are weak: summarizing a lead, inferring fit from firmographics, spotting missing data and drafting a relevant first sequence step. It should not silently change lifecycle stages, overwrite owner-entered fields or send email on its own.
A good division of labor is: the agent proposes, a rep approves, HubSpot records. That keeps the CRM clean and makes the audit trail meaningful.
2. OAuth and scopes
Create an app in HubSpot, configure the redirect URL, and send the user to the authorization URL with the scopes you need. Exchange the returned code at the date-based token endpoint. HubSpot is deprecating the legacy /oauth/v1/token endpoints on 16 February 2027, so use the current versioned endpoint for new work.
curl -s -X POST https://api.hubapi.com/oauth/2026-09/token \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "grant_type=authorization_code" \
--data-urlencode "client_id=$HUBSPOT_CLIENT_ID" \
--data-urlencode "client_secret=$HUBSPOT_CLIENT_SECRET" \
--data-urlencode "redirect_uri=$HUBSPOT_REDIRECT_URI" \
--data-urlencode "code=$HUBSPOT_CODE"
Access tokens expire after about 30 minutes; store the refresh token and renew before expiry. Request only the scopes you use: crm.objects.contacts.read, crm.objects.contacts.write, crm.objects.deals.read and, if needed, crm.objects.companies.read. A token reflects the scopes, not the installing user's record-level permissions, so do not treat it as a per-rep authorization boundary.
3. Read the contact and deal schema
HubSpot properties have an internal name and a label. The API uses the internal name; a label such as "Lifecycle Stage" is not a valid property key. Fetch the property definitions for each object before you build a prompt.
| Object | Common internal names | Note |
|---|---|---|
| Contact | email, firstname, lastname, jobtitle, lifecyclestage | email is the primary unique identifier. |
| Company | name, domain, industry, annualrevenue | Use the domain for firmographic enrichment. |
| Deal | dealname, amount, dealstage, closedate, pipeline | Stage and amount are high-impact fields. |
Lifecycle stage can only move forward through the default stages. To move it backward, the value must be cleared first, either manually or through a workflow. Do not let an agent attempt a backward move and call the resulting error a model failure.
4. Enrich without overwriting
Search for an existing contact by email before creating anything. The CRM search endpoint accepts filters and returns up to 200 records per page; use it rather than listing every contact. For a batch, use the batch read endpoint with idProperty: "email".
POST /crm/objects/2026-09/contacts/search
{
"filterGroups": [{
"filters": [{
"propertyName": "email",
"operator": "EQ",
"value": "lead@company.test"
}]
}],
"properties": ["email", "firstname", "lastname", "jobtitle", "lifecyclestage"]
}
Write only when the field is empty, or write to a dedicated ai_* property that a human can review. Store provenance in a custom property or an external audit log: model, prompt version, source URL and timestamp. Never overwrite a rep's note or a closed-won amount because the model inferred something different.
5. Score and draft with structured output
Ask for one JSON object with a fixed schema. Keep the prompt to the fields the task needs; sending the entire contact record increases cost and leaks more personal data into the context than necessary.
{
"fit_score": 78,
"intent": "evaluating",
"reasons": ["Matches ICP industry", "Visited pricing twice"],
"missing_data": ["employee_count", "current_vendor"],
"draft_subject": "A shorter setup for your RevOps team",
"draft_body": "Hi {{first_name}} — saw you are hiring a RevOps lead...",
"consent_status": "unknown"
}
Validate the score range, the allowed intent values and the draft length before you save anything. A score is a prioritization aid, not a truth claim. Show the reasons next to it so a rep can disagree without reverse-engineering the number. The draft is a sequence step for a human to review and send, not an email the agent dispatches.
6. Consent, audit and limits
An email address is not consent. Check the contact's marketing status and legal basis before any marketing action, and treat an unknown status as no consent. Property names vary by portal; confirm them through the properties API rather than assuming. Consent rules are jurisdiction-specific, so have counsel review the workflow before it sends anything.
| Limit | Value | Control |
|---|---|---|
| Search requests | 5 per second per account | Queue and back off; do not parallelize blindly. |
| Search results | 10,000 per query | Narrow filters; do not page forever. |
| Page size | 200 records | Use the after cursor. |
| Batch operations | 100 records | Split larger jobs. |
| Access token | About 30 minutes | Refresh before expiry and store tokens encrypted. |
Log every write with the contact ID, property, old value, new value, approval and model version. For cost, count one enrichment call plus one scoring/drafting call per lead, plus any embedding used for similarity. On Plugsky, paid plans start at $8/month; Builder and Scale have no monthly token cap under fair-use limits. See pricing.
For the wider sales workflow, see build an AI sales agent and how to build sales agents.
FAQ
How do I connect an AI agent to HubSpot?
Create a HubSpot app with OAuth and CRM scopes, exchange the authorization code for an access and refresh token, and call the CRM API with the bearer token.
Which scopes does the agent need?
At minimum crm.objects.contacts.read and crm.objects.contacts.write. Add crm.objects.deals.read or crm.objects.companies.read only if the workflow uses those objects.
Can the agent update lifecycle stage?
It can propose a stage, but lifecycle stage only moves forward by default and backward moves require clearing the value first. Keep stage changes behind human approval.
How do I handle consent?
Check the contact's marketing status and legal basis before any marketing action, treat unknown as no consent, and have counsel review the workflow. An email address alone is not consent.
What are the HubSpot API limits?
CRM search is limited to 5 requests per second, 10,000 results per query and 200 records per page. Batch operations are limited to 100 records, and access tokens last about 30 minutes.
Sources checked 20 November 2026: HubSpot OAuth tokens 2026-09; HubSpot contacts API; HubSpot CRM search API. Product behavior, endpoint support and plan limits can change; re-check the primary documentation before production rollout.