Automate HubSpot Contacts Import with n8n Pagination

1. Opening Problem Statement

Meet Sarah, a busy sales manager at a fast-growing tech startup. Every week, she manually exports thousands of contacts from HubSpot CRM to analyze her sales pipeline and segment leads for targeted campaigns. The export process is tedious, often taking hours due to manual page-by-page data retrieval limits imposed by HubSpot’s API. Sometimes, data overlaps or omissions happen, leading to inaccurate reports and lost opportunities. Sarah dreams of automating this entire process – fetching all her contacts in one seamless flow, saving time and boosting her team’s productivity.

2. What This Automation Does

This specific n8n workflow automates bulk retrieval of HubSpot contacts using the CRM API with pagination handling. When triggered manually, the workflow:

• Initiates API requests to HubSpot to fetch 100 contacts per page.
• Detects if there’s a next page via a paging pointer in the API response.
• Waits 5 seconds between requests to respect API rate limits.
• Loops through all pages automatically until all contacts are retrieved.
• Aggregates all contact data into one combined dataset for easy export or further processing.
• Eliminates manual downloads, significantly reducing retrieval time from hours to minutes.

3. Prerequisites ⚙️

• n8n account (cloud or self-hosted) 🔌
• HubSpot API key with CRM contacts read permissions 🔑
• Basic familiarity with n8n interface and manual workflow triggering ⏱️

4. Step-by-Step Guide

Step 1: Start with a Manual Trigger

In your n8n editor, drag the Manual Trigger node. This allows you to execute the workflow on demand to fetch and consolidate contacts anytime.

Step 2: Configure the Initial URL Setup

Add a Function node named “Config URL”. Enter the JavaScript below to set the starting API endpoint URL for fetching contacts. It also dynamically updates the URL if the next page link exists from prior steps.

let next = 'https://api.hubapi.com/crm/v3/objects/contacts';

if (items[0].json.next) {
  next = items[0].json.next;
}

return [
  {
    json: { next: next }
  }
];

This JavaScript checks if there is a “next” field in the incoming data to continue pagination; otherwise, it sets the URL to the initial API endpoint.

Step 3: Make the HTTP Request to HubSpot API

Add an HTTP Request node configured as follows:

• Set the URL dynamically: {{$node["Config URL"].json["next"]}}
• Query parameters include your API key (hapikey) and limit set to 100 contacts per page.
• Use GET method by default.

This captures one page of contact data from HubSpot.

Step 4: Insert No Operation Node for Flow Organization

Add a NoOp node next. It acts as a simple pass-through, useful for making the flow readable and maintainable.

Step 5: Pause Between Requests with a Wait Function

The Wait node is a Function node that pauses execution for 5 seconds between page fetches to avoid API rate limiting issues.

return new Promise((resolve, reject) => {
  setTimeout(() => { resolve([{ json: {} }]) }, 5000);
})

Step 6: Check for Pagination

Next, add an If node named “Check if pagination?” to determine whether more pages exist. Configure it to check if the HTTP response includes the paging object:

• Use a boolean condition {{$node["HTTP Request"].json["paging"] ? true : false}} equals true.

Step 7: Set the Next URL for Subsequent Requests

If more pages exist, the workflow uses a Set node named “Set next URL” to update the pagination URL. It extracts the next page link from the API response:

{{ $node["HTTP Request"].json["paging"]["next"]["link"] }}

This link feeds back into the “Config URL” node to continue fetching subsequent pages.

Step 8: Combine All Pages of Data

Once the final page is reached (pagination is false), the last Function node “Combine all data” aggregates all contact results from previous HTTP requests into one array for easy use.

const allData = [];

let counter = 0;
do {
  try {
    const items = $items("HTTP Request", 0, counter).map(item => item.json.results);
    const aja = items[0].map(item => ({ json: item }));
    allData.push.apply(allData, aja);
  } catch (error) {
    return allData;
  }
  counter++;
} while(true);

This code loops through each “HTTP Request” node execution to collect contact data until no more pages are available.

5. Customizations ✏️

• Change Contact Fields: In the HTTP Request node’s URL, append additional query parameters to specify which contact fields to retrieve.
• Adjust Pagination Limit: Modify the limit query parameter in the HTTP Request node to fetch fewer or more contacts per page, balancing speed vs. API limits.
• Add Data Export: Insert a Google Sheets node after “Combine all data” to export results directly into a spreadsheet for analysis.
• Automatic Scheduling: Replace Manual Trigger with Cron node to automate the workflow daily or weekly.

6. Troubleshooting 🔧

Problem: “HTTP 401 Unauthorized”

Cause: Invalid or missing HubSpot API key.

Solution: Double-check your API key in the HTTP Request’s query parameters. Ensure it’s active and has the right permissions.

Problem: Workflow never completes or loops infinitely.

Cause: Pagination link not detected or incorrect JSON path in “Set next URL” node.

Solution: Verify the JSON path paging.next.link matches your API response structure exactly.

7. Pre-Production Checklist ✅

• Test the Manual Trigger to ensure it starts flows correctly.
• Confirm your HubSpot API key works by making a single HTTP Request node call.
• Check that the “Check if pagination?” node accurately detects if more data pages exist.
• Validate the “Set next URL” node’s JSON path corresponds to the actual API response.
• Run the workflow and verify combined data output includes all expected contacts.

8. Deployment Guide

Once tested, activate your workflow in n8n by toggling the active switch. Use the manual trigger for on-demand data refresh or swap to a Cron node for scheduled automation. Regularly monitor workflow execution logs via the n8n dashboard to catch any API errors or interruptions early.

9. FAQs

Q: Can I use OAuth instead of API key for HubSpot?
A: Yes, you can configure OAuth credentials and adjust the HTTP Request accordingly to use Bearer tokens.

Q: Does this consume many API credits?
A: Each request counts against your HubSpot plan rate limits. The workflow batches contacts 100 per call to optimize usage.

Q: Is my data secure with this workflow?
A: Yes, all processing happens within your n8n environment. Maintain secure credentials management in n8n to protect API keys.

10. Conclusion

By following this guide, you’ve created a robust n8n workflow that automates the retrieval of all your HubSpot contacts using API pagination. This eliminates manual exports and consolidates your data efficiently, saving you hours every week while reducing errors. Next, consider expanding this workflow to automatically update your internal databases or trigger email campaigns based on the latest contact data. Your automation journey just got a powerful boost!