How to Connect HubSpot to n8n

You need HubSpot data flowing into n8n workflows. This guide shows you exactly how to authenticate HubSpot in n8n using either API keys or OAuth2, configure the native HubSpot node, and build your first working automation.

n8n instance running. Self-hosted (Docker, npm, or cloud VM) or n8n Cloud account. Version 0.220.0 or later recommended for latest HubSpot node features.

HubSpot account with API

access. Free tier works. You need Settings access to generate credentials. Marketing Hub Starter or higher if you plan to use custom properties or advanced contact segmentation.

5 minutes. That's how long the credential setup takes if you follow these steps exactly.

Use API

Key if:

• You're the only person running these workflows
• Your n8n instance is self-hosted and secure
• You need quick setup for internal automations

Use OAuth2 if:

• Multiple team members will use the connection
• You're building workflows for clients
• You need granular permission scopes
• Your n8n instance is accessible to others

API

keys have full account access. OAuth2 lets you limit permissions to specific HubSpot scopes (contacts only, deals only, etc.).

Log into HubSpot. Click the settings gear icon (top right).

Navigate to Integrations > Private Apps (left sidebar). If you see "API

Key" instead, HubSpot has moved you to the legacy system. Use Private Apps instead.

Click Create a private app.

Name it: "n8n Automation" or something descriptive.

Scopes tab: Select the permissions you need. For most workflows, enable:

• crm.objects.contacts.read and crm.objects.contacts.write
• crm.objects.companies.read and crm.objects.companies.write
• crm.objects.deals.read and crm.objects.deals.write

Click Create app. HubSpot shows your access token once. Copy it immediately.

Store this token in a password manager. You cannot retrieve it again. If you lose it, you'll need to regenerate and update all n8n workflows.

Open your n8n instance. Go to Credentials (left sidebar, or /credentials in the URL).

Click Add Credential. Search for "HubSpot" and select HubSpot API

.

Credential Name: "HubSpot Production" (or whatever helps you identify this connection later).

Access Token: Paste the private app token from Step 1.

Click Save.

n8n does not test the credential at this stage. You'll verify it works when you run a workflow.

If you chose OAuth2 instead of API

key, follow these steps.

In HubSpot, go to Settings > Integrations > Private Apps. Click Create a private app.

Basic Info tab:

• App name: "n8n OAuth Integration"
• Description: "Workflow automation via n8n"

Scopes tab: Select the same permissions as the API

key method.

Settings tab: Note the Client ID and Client Secret. You'll need both.

In n8n, go to Credentials > Add Credential. Select HubSpot OAuth2 API

.

Credential Name: "HubSpot OAuth Production"

Client ID: Paste from HubSpot.

Client Secret: Paste from HubSpot.

OAuth Redirect URL: Copy this from n8n. It looks like https://your-n8n-instance.com/rest/oauth2-credential/callback.

Go back to HubSpot. In your private app settings, add the OAuth Redirect URL to Redirect URLs.

Return to n8n. Click Connect my account. HubSpot opens in a new window. Authorize the app.

n8n confirms the connection. Click Save.

Create a new workflow in n8n. Click the + button to add a node.

Add a Manual Trigger node. This lets you test the workflow on demand.

Click + again. Search for "HubSpot" and add the HubSpot node.

Credential to connect with: Select the credential you created (HubSpot Production or HubSpot OAuth Production).

Resource: Contact

Operation: Get All

Return All: Toggle ON (this retrieves all contacts, not just the first 100).

Click Execute Node. If configured correctly, n8n returns your HubSpot contacts as JSON.

If you see an error:

• "Invalid access token" means your API

  API

  Click to read the full definition in our AI & Automation Glossary.

  key is wrong or expired. Regenerate it in HubSpot.
• "Insufficient permissions" means your private app needs additional scopes. Go back to HubSpot and add them.
• "Rate limit exceeded" means you hit HubSpot's API

  API

  Click to read the full definition in our AI & Automation Glossary.

  limits (100 requests per 10 seconds for most endpoints). Add a Wait node between operations.

You rarely pull HubSpot data just to look at it. You send it somewhere else.

Example: Create contacts in HubSpot from Google Sheets

1. Google Sheets Trigger node: Set to trigger when a new row is added.

2. HubSpot node: Resource = Contact, Operation = Create.

3. Map fields: Click "Add Field" and match Google Sheets columns to HubSpot properties:

   • Email: ={{ $json["Email"] }}
   • First Name: ={{ $json["First Name"] }}
   • Last Name: ={{ $json["Last Name"] }}
   • Phone: ={{ $json["Phone"] }}
4. Execute Workflow. New Google Sheets rows now create HubSpot contacts automatically.

Example: Update deal stages based on Slack commands

1. Slack Trigger node: Listen for a specific slash command like /close-deal [deal-id].

2. HubSpot node: Resource = Deal, Operation = Update.

3. Deal ID: ={{ $json["text"].split(' ')[1] }} (extracts the deal ID from the Slack command).

4. Deal Stage: Set to "closedwon" or your pipeline's closed stage ID.

5. Slack node: Send a confirmation message back to the channel.

Contacts:

• Get All: Retrieve all contacts (respects filters if you add them).
• Get: Fetch a single contact by ID or email.
• Create: Add a new contact. Requires email at minimum.
• Update: Modify existing contact properties. Use contact ID or email as identifier.
• Delete: Remove a contact permanently.

Companies:

• Get All / Get / Create / Update / Delete: Same pattern as contacts.
• Add Contact to Company: Use the "Associate" operation. Requires both contact ID and company ID.

Deals:

• Get All / Get / Create / Update / Delete: Same pattern.
• Get Recently Created / Modified: Useful for syncing only changed deals.

Custom Objects:

• HubSpot Enterprise accounts can create custom objects (e.g., "Projects", "Invoices").
• n8n supports these via the Custom Object resource type.
• You'll need the object type ID from HubSpot (found in Settings > Data Management > Objects).

HubSpot enforces strict rate limits:

• 100 requests per 10 seconds for most endpoints.
• 4 requests per second for search endpoints.
• 150 requests per 10 seconds for batch operations.

If you hit limits:

Add a Wait node between HubSpot operations. Set it to 100ms (0.1 seconds). This throttles requests to ~10 per second, well under the limit.

Use batch operations when possible. The HubSpot node supports batch create/update for contacts, companies, and deals. This counts as one API

call for up to 100 records.

Enable error workflows in n8n. If a HubSpot node fails due to rate limiting, the error workflow can wait 10 seconds and retry automatically.

Before you activate any HubSpot workflow:

Test with a sandbox contact. Create a contact with a test email (e.g., test+hubspot@yourdomain.com). Run your workflow against this contact first.

Check HubSpot's activity log. In HubSpot, open any contact/company/deal record and view the Activity tab. You'll see API

calls from n8n listed with timestamps.

Verify field mappings. HubSpot uses internal property names that don't always match the UI labels. For example, "First Name" in the UI is firstname in the API

. Check HubSpot's property settings to confirm exact names.

Monitor execution logs. In n8n, go to Executions (left sidebar). Every workflow run is logged. Click any execution to see the full data flow and spot errors.

Never hardcode API

keys in workflows. Always use n8n's credential system.

Rotate API

keys quarterly. Generate a new HubSpot private app token every 90 days. Update the n8n credential. Old workflows continue working immediately.

Use separate credentials for dev/staging/production. Create different HubSpot private apps for each environment. This prevents test workflows from touching live customer data.

Audit credential access. In n8n Cloud or self-hosted with user management, restrict who can view or edit HubSpot credentials. Only workflow admins need this access.

You now have HubSpot connected to n8n and a working test workflow.

Build a contact enrichment pipeline. Pull new HubSpot contacts, send them to Clearbit or Hunter.io for enrichment, then update HubSpot with the new data.

Automate deal stage progression. When a deal reaches "Proposal Sent", trigger a Slack notification and create a follow-up task in Asana.

Sync HubSpot to your data warehouse. Schedule a daily workflow that exports all contacts, companies, and deals to BigQuery or Snowflake for reporting.

The HubSpot node in n8n supports every major API

endpoint. If you can do it in HubSpot's UI, you can automate it in n8n.