How to Integrate Bolt.new with HubSpot

HubSpot's Private Apps are the recommended authentication method for server-to-server integrations. Unlike OAuth apps that require a multi-step authorization flow and involve redirecting users, Private Apps generate a long-lived access token that you use directly — similar to an API key but with granular scope control. To create a Private App, log into HubSpot and go to Settings (the gear icon in the top navigation) → Integrations → Private Apps. Click 'Create a private app.' Give it a descriptive name like 'My Bolt App' so you can identify it later. On the Scopes tab, select the permissions your app needs. For CRM access, the key scopes are: crm.objects.contacts.read (read contacts), crm.objects.contacts.write (create and update contacts), crm.objects.deals.read (read deals), crm.objects.deals.write (create and update deals), crm.objects.companies.read (read companies), and forms (access HubSpot forms). Only select the scopes you actually need — least-privilege access is a security best practice. Click 'Create app.' HubSpot will show you the access token — a long string starting with 'pat-'. Copy it immediately. The token is only displayed once in full — if you miss it, you will need to rotate the token in the Private App settings to generate a new one. The access token you just copied goes in your Bolt.new project's .env file as HUBSPOT_ACCESS_TOKEN. This token is scoped to the permissions you selected and is tied to your HubSpot portal. Treat it like a password — do not share it or commit it to version control. If it is ever compromised, rotate it immediately in the Private App settings. Also note your HubSpot Portal ID for the tracking script. You can find it in the URL when logged into HubSpot (app.hubspot.com/contacts/YOUR_PORTAL_ID/) or under Settings → Account Setup → Account. Store this as NEXT_PUBLIC_HUBSPOT_PORTAL_ID in .env since it is safe to expose client-side.

1# .env
2# HubSpot Private App token — server-side only, never use NEXT_PUBLIC_ prefix
3# Get this from HubSpot Settings → Integrations → Private Apps → Create
4HUBSPOT_ACCESS_TOKEN=pat-na1-your_token_here
5
6# HubSpot Portal ID — safe for client-side use (in tracking script)
7# Find this in your HubSpot URL: app.hubspot.com/contacts/YOUR_PORTAL_ID/
8NEXT_PUBLIC_HUBSPOT_PORTAL_ID=12345678

With credentials configured, build the HubSpot API service layer in Bolt.new. This consists of a reusable utility module (lib/hubspot.ts) that handles authentication headers and common API patterns, plus Next.js API routes for specific CRM operations. The HubSpot REST API base URL is https://api.hubapi.com. Authentication is added as a Bearer token in the Authorization header. The key v3 CRM endpoints are: POST /crm/v3/objects/contacts (create contact), GET /crm/v3/objects/contacts/{contactId} (get contact by ID), PATCH /crm/v3/objects/contacts/{contactId} (update contact), and POST /crm/v3/objects/contacts/search (search contacts by filter criteria). For upsert behavior (create if not exists, update if exists), use the crm/v3/objects/contacts endpoint with the idProperty parameter set to email — HubSpot will match on email address and update the existing contact rather than creating a duplicate. Paste the Bolt prompt below to scaffold the HubSpot service module and the contacts API routes. After Bolt generates the code, verify that lib/hubspot.ts reads from process.env.HUBSPOT_ACCESS_TOKEN and that no token value appears in any client-side file. Check that the contact creation route handles HubSpot's 409 Conflict response (which occurs when you try to create a contact with an email that already exists in the CRM) gracefully — the correct behavior in most cases is to update the existing contact rather than returning an error. HubSpot's API returns contacts with a properties object containing all the CRM field values. Standard contact properties include firstname, lastname, email, company, phone, and jobtitle. Custom properties you create in HubSpot's property settings are accessed by their internal name (a lowercase_snake_case string you define when creating the property).

1// lib/hubspot.ts
2const HUBSPOT_BASE = 'https://api.hubapi.com';
3
4async function hubspotFetch<T>(endpoint: string, options: RequestInit = {}): Promise<T> {
5  const token = process.env.HUBSPOT_ACCESS_TOKEN;
6  if (!token) throw new Error('HUBSPOT_ACCESS_TOKEN not configured');
7
8  const res = await fetch(`${HUBSPOT_BASE}${endpoint}`, {
9    ...options,
10    headers: {
11      Authorization: `Bearer ${token}`,
12      'Content-Type': 'application/json',
13      ...options.headers,
14    },
15  });
16
17  if (!res.ok) {
18    const error = await res.json().catch(() => ({ message: res.statusText }));
19    throw Object.assign(new Error(error.message ?? 'HubSpot API error'), { status: res.status, body: error });
20  }
21
22  return res.json();
23}
24
25export interface HubSpotContactProperties {
26  firstname?: string;
27  lastname?: string;
28  email?: string;
29  company?: string;
30  phone?: string;
31  jobtitle?: string;
32  [key: string]: string | undefined;
33}
34
35export async function createOrUpdateContact(properties: HubSpotContactProperties) {
36  return hubspotFetch('/crm/v3/objects/contacts', {
37    method: 'POST',
38    body: JSON.stringify({
39      properties,
40      // Upsert by email — updates existing contact if email matches
41    }),
42  });
43}
44
45export async function listContacts(limit = 10, after?: string) {
46  const params = new URLSearchParams({
47    limit: limit.toString(),
48    properties: 'firstname,lastname,email,company,phone,createdate',
49    ...(after && { after }),
50  });
51  return hubspotFetch(`/crm/v3/objects/contacts?${params}`);
52}
53
54export async function searchContacts(query: string) {
55  return hubspotFetch('/crm/v3/objects/contacts/search', {
56    method: 'POST',
57    body: JSON.stringify({
58      query,
59      properties: ['firstname', 'lastname', 'email', 'company'],
60      limit: 20,
61    }),
62  });
63}
64
65export async function listDeals(limit = 10, after?: string) {
66  const params = new URLSearchParams({
67    limit: limit.toString(),
68    properties: 'dealname,amount,dealstage,closedate,hubspot_owner_id',
69    ...(after && { after }),
70  });
71  return hubspotFetch(`/crm/v3/objects/deals?${params}`);
72}

Beyond the REST API, HubSpot provides two client-side tools that are extremely valuable for marketing integrations: the HubSpot tracking script (which tracks page visits and identifies visitors across sessions) and the Forms API (which lets you embed HubSpot-managed forms or programmatically submit to them). The HubSpot tracking script, called the HubSpot JavaScript API or hs-tracking-code.js, is a small async script that you add to your site's HTML head. It tracks page views, identifies contacts who fill out forms, and enables HubSpot's live chat widget if you have that configured. To add it in a Next.js app, use a Script component in your root layout with the src pointing to //js.hs-scripts.com/YOUR_PORTAL_ID.js. The portal ID comes from your .env file as NEXT_PUBLIC_HUBSPOT_PORTAL_ID. This script is completely client-side and safe to include since it does not expose any sensitive credentials. HubSpot Forms gives you two options for embedding forms. The simplest is the Embed Code: HubSpot generates a small JavaScript snippet in your Forms dashboard (Marketing → Forms → select a form → Actions → Share) that renders the form with full HubSpot styling and submission handling. Paste this snippet into a React component using useEffect to inject the form script — similar to the Calendly embed pattern. The programmatic approach uses the HubSpot Forms Submit API: POST to https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formGuid} with a JSON payload containing the form fields. This approach lets you use your own custom React form while still submitting data to HubSpot's form system, which triggers HubSpot workflows, email notifications, and lead nurture sequences you have configured in HubSpot. The portal ID and form GUID are both public values — no access token required for form submissions, since this endpoint is designed for client-side use.

1// components/HubSpotContactForm.tsx
2'use client';
3import { useState } from 'react';
4
5interface FormData {
6  firstname: string;
7  lastname: string;
8  email: string;
9  company: string;
10}
11
12export function HubSpotContactForm() {
13  const [formData, setFormData] = useState<FormData>({
14    firstname: '', lastname: '', email: '', company: ''
15  });
16  const [status, setStatus] = useState<'idle' | 'loading' | 'success' | 'error'>('idle');
17
18  async function handleSubmit(e: React.FormEvent) {
19    e.preventDefault();
20    setStatus('loading');
21
22    const portalId = process.env.NEXT_PUBLIC_HUBSPOT_PORTAL_ID;
23    const formGuid = process.env.NEXT_PUBLIC_HUBSPOT_FORM_GUID;
24
25    try {
26      const res = await fetch(
27        `https://api.hsforms.com/submissions/v3/integration/submit/${portalId}/${formGuid}`,
28        {
29          method: 'POST',
30          headers: { 'Content-Type': 'application/json' },
31          body: JSON.stringify({
32            fields: Object.entries(formData).map(([name, value]) => ({ name, value })),
33            context: { pageUri: window.location.href, pageName: document.title },
34          }),
35        }
36      );
37
38      if (res.ok) {
39        setStatus('success');
40        setFormData({ firstname: '', lastname: '', email: '', company: '' });
41      } else {
42        setStatus('error');
43      }
44    } catch {
45      setStatus('error');
46    }
47  }
48
49  if (status === 'success') {
50    return <div className="rounded-lg bg-green-50 p-6 text-green-800">Thanks! We will be in touch soon.</div>;
51  }
52
53  return (
54    <form onSubmit={handleSubmit} className="space-y-4">
55      <div className="grid grid-cols-2 gap-4">
56        <input required placeholder="First name" value={formData.firstname}
57          onChange={(e) => setFormData({ ...formData, firstname: e.target.value })}
58          className="rounded border p-2 w-full" />
59        <input required placeholder="Last name" value={formData.lastname}
60          onChange={(e) => setFormData({ ...formData, lastname: e.target.value })}
61          className="rounded border p-2 w-full" />
62      </div>
63      <input required type="email" placeholder="Email" value={formData.email}
64        onChange={(e) => setFormData({ ...formData, email: e.target.value })}
65        className="rounded border p-2 w-full" />
66      <input placeholder="Company" value={formData.company}
67        onChange={(e) => setFormData({ ...formData, company: e.target.value })}
68        className="rounded border p-2 w-full" />
69      <button type="submit" disabled={status === 'loading'}
70        className="w-full rounded bg-orange-500 py-2 font-medium text-white hover:bg-orange-600 disabled:opacity-50">
71        {status === 'loading' ? 'Submitting...' : 'Get in Touch'}
72      </button>
73      {status === 'error' && <p className="text-red-600 text-sm">Something went wrong. Please try again.</p>}
74    </form>
75  );
76}

For internal tools and CRM dashboards, displaying the HubSpot deals pipeline in your app's interface is one of the most valuable integration features. Sales teams can view their pipeline in a custom interface that matches the company's design system, integrated alongside other internal tools — without switching to HubSpot's default UI. The HubSpot Deals API returns deals with properties including dealname, amount, dealstage, closedate, and hubspot_owner_id. Deal stages are specific to your HubSpot pipeline — the default stages are 'appointmentscheduled,' 'qualifiedtobuy,' 'presentationscheduled,' 'decisionmakerboughtin,' 'contractsent,' 'closedwon,' and 'closedlost.' You can retrieve your pipeline's custom stage IDs from HubSpot Settings → CRM → Deals → Pipelines. For a Kanban-style pipeline view, group deals by their dealstage property and display each stage as a column. React state manages the current view (by stage, by owner, by expected close date). The amount field is returned as a string from HubSpot — parse it to a number and format as currency for display. Add pagination handling for large deal pipelines. HubSpot's list endpoints return up to 100 items per page with a paging.next.after cursor for the next page. The API route should accept an 'after' query parameter for cursor-based pagination, and the React component can implement infinite scroll or 'Load more' functionality using the returned cursor value.

1// app/api/hubspot/deals/route.ts
2import { NextResponse } from 'next/server';
3import { listDeals } from '@/lib/hubspot';
4
5export async function GET(request: Request) {
6  const { searchParams } = new URL(request.url);
7  const limit = parseInt(searchParams.get('limit') ?? '50');
8  const after = searchParams.get('after') ?? undefined;
9
10  try {
11    const data = await listDeals(limit, after) as {
12      results: Array<{
13        id: string;
14        properties: {
15          dealname: string;
16          amount: string;
17          dealstage: string;
18          closedate: string;
19        };
20      }>;
21      paging?: { next?: { after: string } };
22    };
23
24    const deals = data.results.map((deal) => ({
25      id: deal.id,
26      name: deal.properties.dealname,
27      amount: parseFloat(deal.properties.amount ?? '0'),
28      stage: deal.properties.dealstage,
29      closeDate: deal.properties.closedate,
30    }));
31
32    return NextResponse.json({
33      deals,
34      nextCursor: data.paging?.next?.after ?? null,
35    });
36  } catch (error) {
37    const message = error instanceof Error ? error.message : 'Unknown error';
38    return NextResponse.json({ error: message }, { status: 500 });
39  }
40}