How to Integrate HubSpot with V0

HubSpot's modern API uses Private Apps for server-to-server integrations. Unlike the older OAuth flow, a Private App gives you a static access token tied to a specific set of permission scopes — much simpler for internal tools and single-tenant integrations. To create a Private App, log into your HubSpot account and navigate to Settings (the gear icon in the top-right). In the left sidebar, scroll to Integrations and click Private Apps. Click Create a private app. Give it a name like 'V0 Integration' and a description. On the Scopes tab, select the permissions your app needs. For reading contacts and deals you need crm.objects.contacts.read and crm.objects.deals.read. For creating or updating records, add the corresponding write scopes. For tickets, add crm.objects.tickets.read and crm.objects.tickets.write. After configuring scopes, click Create app. HubSpot will show you a long access token starting with pat-na1- (or a similar regional prefix). Copy this token immediately and store it somewhere secure — HubSpot will not show it again in full. This token is what your Next.js API route will use to authenticate all requests to HubSpot. Important: never put this token in your V0 chat messages or in any code you commit to GitHub. It grants broad CRM access and should only ever live in environment variables. HubSpot's Private App tokens do not expire on their own, but you can rotate them at any time from the Private Apps settings page.

With your authentication plan in place, use V0 to generate the front-end components for your CRM feature. V0 excels at building data tables, Kanban boards, form UIs, and dashboard layouts — exactly the kinds of interfaces that make CRM data useful. The key is to tell V0 the exact API endpoints your components should call so the fetch logic is wired up correctly from the start. For a contact list, ask V0 for a table component that fetches from /api/hubspot/contacts. For a deal pipeline, ask for a Kanban board that groups data from /api/hubspot/deals by a stage field. For a lead form, specify the POST endpoint and the fields you need. V0 will generate TypeScript React components with Tailwind CSS styling, including loading states and basic error handling. Review the generated fetch calls in the component code. For GET requests, the pattern should be fetching from your API route with optional query parameters. For POST requests (creating records), the component should serialize form data to JSON and POST it to your API route. Make sure V0's generated components handle the response correctly — for list data, they should map over an array; for creation, they should show a success or error message based on the API response status. If V0 generates placeholder hardcoded data instead of actual fetch calls, prompt it again: 'Update this component to fetch real data from /api/hubspot/contacts instead of using static mock data.' V0 can iterate quickly on the data-fetching logic.

Now build the server-side API route that your V0 components will call. Create the file app/api/hubspot/route.ts in your project. This serverless function runs on Vercel's infrastructure, reads your HubSpot access token from environment variables, and proxies CRM requests to HubSpot's API. Install the official HubSpot Node.js SDK by adding @hubspot/api-client to your package.json dependencies. This package provides typed clients for every HubSpot object type (contacts, deals, companies, tickets) and handles authentication by accepting your access token in the constructor. The API route below handles two operations: a GET request that fetches contacts with optional search filtering, and a POST request that creates a new contact. HubSpot's v3 API uses a properties object pattern — when reading a contact, you specify which properties you want returned; when creating a contact, you set values in a properties object matching HubSpot's internal property names. One critical detail with HubSpot's contacts API: property names are lowercase with underscores, not camelCase. For example, the contact's first name is 'firstname' (one word, no underscore), the last name is 'lastname', and the email is 'email'. Company name is 'company', phone number is 'phone', and lifecycle stage is 'lifecyclestage'. These exact property names must match what HubSpot expects — mismatches silently return empty values rather than throwing an error. For deals, the key properties are 'dealname', 'amount', 'closedate', 'dealstage', and 'pipeline'. The dealstage value must match the internal ID of the stage in your HubSpot pipeline, not the display name. You can find stage IDs in HubSpot Settings → Objects → Deals → Pipelines.

1import { Client } from '@hubspot/api-client';
2import { NextRequest, NextResponse } from 'next/server';
3
4const hubspot = new Client({
5  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
6});
7
8export async function GET(request: NextRequest) {
9  try {
10    const { searchParams } = new URL(request.url);
11    const query = searchParams.get('q');
12
13    let contacts;
14
15    if (query) {
16      // Search contacts by email or name
17      const searchResponse = await hubspot.crm.contacts.searchApi.doSearch({
18        query,
19        limit: 50,
20        properties: ['firstname', 'lastname', 'email', 'company', 'lifecyclestage', 'lastmodifieddate'],
21        filterGroups: [],
22        sorts: [],
23        after: 0,
24      });
25      contacts = searchResponse.results;
26    } else {
27      // Fetch all contacts (paginated)
28      const response = await hubspot.crm.contacts.basicApi.getPage(
29        50,
30        undefined,
31        ['firstname', 'lastname', 'email', 'company', 'lifecyclestage', 'lastmodifieddate']
32      );
33      contacts = response.results;
34    }
35
36    const formatted = contacts.map((c) => ({
37      id: c.id,
38      firstName: c.properties.firstname || '',
39      lastName: c.properties.lastname || '',
40      email: c.properties.email || '',
41      company: c.properties.company || '',
42      lifecycleStage: c.properties.lifecyclestage || '',
43      lastModified: c.properties.lastmodifieddate || '',
44    }));
45
46    return NextResponse.json({ contacts: formatted });
47  } catch (error: unknown) {
48    console.error('HubSpot GET error:', error);
49    return NextResponse.json(
50      { error: 'Failed to fetch contacts' },
51      { status: 500 }
52    );
53  }
54}
55
56export async function POST(request: NextRequest) {
57  try {
58    const body = await request.json();
59    const { firstName, lastName, email, company, phone } = body;
60
61    if (!email) {
62      return NextResponse.json(
63        { error: 'Email is required' },
64        { status: 400 }
65      );
66    }
67
68    const contact = await hubspot.crm.contacts.basicApi.create({
69      properties: {
70        firstname: firstName || '',
71        lastname: lastName || '',
72        email,
73        company: company || '',
74        phone: phone || '',
75      },
76      associations: [],
77    });
78
79    return NextResponse.json(
80      { id: contact.id, message: 'Contact created successfully' },
81      { status: 201 }
82    );
83  } catch (error: unknown) {
84    console.error('HubSpot POST error:', error);
85    return NextResponse.json(
86      { error: 'Failed to create contact' },
87      { status: 500 }
88    );
89  }
90}

Your API route reads HUBSPOT_ACCESS_TOKEN from environment variables. You need to add this to Vercel so the serverless function can authenticate with HubSpot when your app is deployed. Open your Vercel Dashboard and navigate to your project. Click the Settings tab, then click Environment Variables in the left sidebar. In the form, enter HUBSPOT_ACCESS_TOKEN as the key and paste your Private App token (the long string starting with pat-na1-) as the value. Set the environment scope to Production, Preview, and Development so the route works across all deployments. Important: do not add the NEXT_PUBLIC_ prefix to this variable. The NEXT_PUBLIC_ prefix would expose the value in the browser's JavaScript bundle, making your access token visible to anyone who inspects your app's network requests or source code. The HubSpot access token must only be readable server-side in the API route. If your app needs to display the HubSpot portal ID (a non-sensitive identifier used in some embed scenarios), you can add NEXT_PUBLIC_HUBSPOT_PORTAL_ID with the appropriate prefix since it is not a secret. Your portal ID appears in the URL when you are logged into HubSpot, for example hub.hubspot.com/contacts/12345678 — the number is the portal ID. After saving the environment variables, trigger a new deployment by pushing any commit to your GitHub repository or clicking Redeploy in the Vercel Dashboard. Environment variable changes only take effect after redeployment. For local development, add HUBSPOT_ACCESS_TOKEN to your .env.local file (which should already be in your .gitignore).

Once contacts are working, extending the integration to deals and tickets follows the same pattern. Create additional API routes — app/api/hubspot/deals/route.ts for deals and app/api/hubspot/tickets/route.ts for tickets — each using the hubspot.crm.deals and hubspot.crm.tickets client namespaces from the same @hubspot/api-client package. For deals, the critical properties are dealname, amount, closedate, dealstage, and pipeline. The dealstage must be an internal ID, not the display name. To find stage IDs programmatically, call hubspot.crm.pipelines.pipelinesApi.getAll('deals') which returns all pipelines and their stage objects with both the label (display name) and the ID you need for filtering and creating deals. For a Kanban pipeline board, fetch all open deals and group them client-side by the dealstage property. Your V0-generated Kanban component should accept a deals array and render columns for each stage. Ask V0 to generate the Kanban layout with drag-and-drop reordering if you need that interactivity — V0 can scaffold @dnd-kit/core for this purpose. For tickets, the key properties are subject, content, hs_ticket_priority, and hs_pipeline_stage. Tickets also have associations to contacts and companies, which you can fetch by including associations in the API request or by making a follow-up call to hubspot.crm.associations.v4.basicApi. For complex integrations that require webhooks from HubSpot (for real-time CRM sync), custom object support, or multi-portal setups, RapidDev's team can help architect the full solution including webhook verification and database synchronization.

1import { Client } from '@hubspot/api-client';
2import { NextRequest, NextResponse } from 'next/server';
3
4const hubspot = new Client({
5  accessToken: process.env.HUBSPOT_ACCESS_TOKEN,
6});
7
8export async function GET(request: NextRequest) {
9  try {
10    const { searchParams } = new URL(request.url);
11    const stage = searchParams.get('stage');
12
13    const filters = stage
14      ? [{ propertyName: 'dealstage', operator: 'EQ' as const, value: stage }]
15      : [];
16
17    const response = await hubspot.crm.deals.searchApi.doSearch({
18      limit: 100,
19      properties: ['dealname', 'amount', 'closedate', 'dealstage', 'pipeline', 'hubspot_owner_id'],
20      filterGroups: filters.length > 0 ? [{ filters }] : [],
21      sorts: [{ propertyName: 'closedate', direction: 'ASCENDING' as const }],
22      after: 0,
23    });
24
25    const deals = response.results.map((d) => ({
26      id: d.id,
27      name: d.properties.dealname || 'Untitled Deal',
28      amount: d.properties.amount ? parseFloat(d.properties.amount) : null,
29      closeDate: d.properties.closedate || '',
30      stage: d.properties.dealstage || '',
31      pipeline: d.properties.pipeline || '',
32    }));
33
34    return NextResponse.json({ deals });
35  } catch (error: unknown) {
36    console.error('HubSpot deals error:', error);
37    return NextResponse.json(
38      { error: 'Failed to fetch deals' },
39      { status: 500 }
40    );
41  }
42}