HubSpot Integration with Workflows
Fetch companies and their associated contacts from HubSpot using Superglue Workflows.
Integrating with HubSpot often involves fetching related data, like companies and their contacts, and transforming it into a specific structure for your application. Superglue Workflows can automate these multi-step processes, making it easier to manage complex data aggregation tasks.
This guide demonstrates how to build and execute a Superglue Workflow to:
- Fetch a list of companies from HubSpot.
- For each company, fetch its associated contacts.
- Combine this data into a nested structure where each company object contains an array of its contacts.
Note: All config objects for individual workflow steps support the full ApiConfig schema. Superglue infers most fields, but you can provide explicit configurations if needed. Workflows themselves are defined and then executed.
Prerequisites
- A HubSpot account with API access.
- A HubSpot Private App and its Access Token (recommended for authentication).
- Superglue SDK installed and configured (see Quick Start).
Installation
Ensure you have the Superglue client and Zod for schema definition:
Authentication
HubSpot’s API uses Bearer token authentication. The simplest way is to create a Private App in your HubSpot developer account and use its Access Token.
Keep this token handy; you’ll provide it as a credential when executing the workflow.
Define Output Schemas with Zod
We’ll define the structure for individual contacts and companies, and then a final schema for the combined data.
Building the Workflow
We’ll use client.buildWorkflow()
to instruct Superglue to create the necessary steps. Superglue will analyze the HubSpot API (using the provided documentation URL) and the instruction to figure out how to fetch companies, then contacts for each company, and combine them.
When buildWorkflow
is called:
- Superglue analyzes the
instruction
and thesystems
(HubSpot API documentation). - It designs a sequence of steps: one to fetch companies, and then a looping mechanism or subsequent steps to fetch contacts for each company using associations.
- It determines the necessary API endpoints (e.g.,
/crm/v3/objects/companies
,/crm/v3/objects/contacts
, and how to query associations). - It generates transformations to fit the data into
hubspotDataSchema
.
The workflow
object returned contains the definition of these steps, including the generated ApiConfig
objects for each API call.
Executing the Workflow
Once the workflow is built, you can execute it using client.executeWorkflow()
. You’ll provide the workflow definition (or its ID if previously saved/upserted) and the necessary runtime credentials.
Expected Output (Simplified)
The result.data
from a successful execution would look something like this:
Understanding the Workflow Internals (Conceptual)
While Superglue abstracts the complexity, the built workflow conceptually involves:
- Step 1: Fetch Companies: An API call to HubSpot’s company endpoint (e.g.,
GET /crm/v3/objects/companies
). It handles pagination to retrieve all companies. - Step 2: Loop/Fetch Associated Contacts: For each company ID obtained in Step 1, Superglue makes further API calls to HubSpot to get associated contacts. This might involve an endpoint like
GET /crm/v4/objects/companies/{companyId}/associations/contacts
or querying the contacts endpoint with filters. - Step 3: Data Transformation & Aggregation: The data from these individual calls is transformed and aggregated according to the
instruction
andresponseSchema
to produce the final nested structure.
Superglue determines the most efficient way to perform these associations and transformations based on the API documentation and your instructions.
Next Steps
- Saving Workflows: You can save the
builtWorkflow
definition usingclient.upsertWorkflow(workflow.id, workflow)
for later execution by ID. - Error Handling: Implement more robust error handling and retry logic for production scenarios.
- Complex Scenarios: Extend this pattern to include more HubSpot objects (Deals, Tickets), apply more complex transformations, or integrate HubSpot data with other systems in a single workflow.
- Explore the API Reference for Workflows and Types for more details.
This guide illustrates the power of Superglue Workflows for orchestrating complex integrations with APIs like HubSpot, automating data fetching, transformation, and aggregation with simple, natural language instructions.