How to Integrate Bolt.new with Pipedrive

Pipedrive uses one of the simplest authentication patterns available in any CRM: a static API token that you add as a query parameter or Authorization Bearer token on every API request. Unlike OAuth flows, there are no redirect URIs, no token expiration (unless you manually regenerate the token), and no scopes to configure — a single token gives you full access to all API endpoints your user account can access. To get your API token, log into Pipedrive and go to your personal settings. Click your avatar in the top-right and select 'Personal preferences.' Navigate to the API tab. You will see your personal API token — a 40-character alphanumeric string. Copy it. This token has the same access level as your Pipedrive user account, so it can read and write all deals, contacts, and pipeline data you have permission to access. Pipedrive offers two ways to pass the API token in requests. Method 1: Add it as a query parameter on every request URL: https://api.pipedrive.com/v1/deals?api_token=YOUR_TOKEN. Method 2: Pass it as a Bearer token in the Authorization header: Authorization: Bearer YOUR_TOKEN. The query parameter approach is simpler for testing; the Authorization header approach is cleaner for production code since tokens do not appear in server access logs. You also need your pipeline ID and stage IDs for creating deals. To find them, make a GET request to https://api.pipedrive.com/v1/stages?api_token=YOUR_TOKEN in a browser or API tool. The response lists all pipeline stages with their IDs, names, and the pipeline they belong to. Stage IDs are small integers (typically 1-50 for accounts with a few pipelines). Store the token in .env as PIPEDRIVE_API_TOKEN. Add your primary pipeline ID as PIPEDRIVE_PIPELINE_ID. These are server-side credentials — never prefix them with NEXT_PUBLIC_ since the API token gives write access to your entire CRM.

1# .env
2# Pipedrive API token — server-side only, never NEXT_PUBLIC_
3# Get from Pipedrive Settings → Personal Preferences → API tab
4# 40-character alphanumeric string that gives full API access
5PIPEDRIVE_API_TOKEN=a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
6
7# Primary pipeline ID for creating new deals
8# Find via: GET https://api.pipedrive.com/v1/stages?api_token={TOKEN}
9PIPEDRIVE_PIPELINE_ID=1
10
11# Optional: stage ID for new inbound leads (first stage in your pipeline)
12PIPEDRIVE_NEW_LEAD_STAGE_ID=1

Create the Pipedrive API service module and the core Next.js API routes for deal and contact operations. Pipedrive's REST API v1 is the current stable version. All endpoints follow standard CRUD patterns and return consistent response shapes with a 'data' field containing the result and a 'success' boolean. The key Pipedrive endpoints are: GET /v1/deals (list deals with filtering by status, pipeline, person, and organization), GET /v1/deals/{id} (single deal with full details), POST /v1/deals (create deal), PUT /v1/deals/{id} (update deal), GET /v1/stages (all pipeline stages), GET /v1/persons (contacts), POST /v1/persons (create contact), GET /v1/organizations (companies), POST /v1/organizations (create company), and POST /v1/notes (add note to a deal, person, or org). For deal listing, the most useful query parameters are: status (open, won, lost, deleted, or all_not_deleted), pipeline_id (filter to a specific pipeline), stage_id (filter to a specific stage), user_id (assigned user filter), start (pagination offset), and limit (up to 500). The response includes an additional_data.pagination object with start, limit, more_items_in_collection, and next_start for pagination. Pipedrive returns custom fields (fields you added in Pipedrive's settings) with auto-generated hash keys like 'abc123def456'. To map these to human-readable names, call GET /v1/dealFields to get the field definitions with their keys and names. Cache this field mapping to avoid fetching it on every request. Build the service module with typed helper functions and test the deal listing endpoint in Bolt's preview. Outbound API calls to api.pipedrive.com work in the WebContainer since they use standard HTTPS — you should see your Pipedrive deals appear in the dashboard immediately.

1// lib/pipedrive.ts
2const PD_BASE = 'https://api.pipedrive.com/v1';
3
4function getToken(): string {
5  const token = process.env.PIPEDRIVE_API_TOKEN;
6  if (!token) throw new Error('PIPEDRIVE_API_TOKEN not configured');
7  return token;
8}
9
10async function pipedriveFetch<T>(
11  endpoint: string,
12  options: RequestInit = {},
13  queryParams: Record<string, string> = {}
14): Promise<T> {
15  const params = new URLSearchParams({ api_token: getToken(), ...queryParams });
16  const url = `${PD_BASE}${endpoint}?${params}`;
17
18  const res = await fetch(url, {
19    ...options,
20    headers: { 'Content-Type': 'application/json', ...options.headers },
21  });
22
23  if (!res.ok) {
24    const body = await res.json().catch(() => ({ error: res.statusText }));
25    throw Object.assign(new Error(body.error ?? 'Pipedrive API error'), {
26      status: res.status,
27      body,
28    });
29  }
30
31  const json = await res.json();
32  if (!json.success) {
33    throw new Error(json.error ?? 'Pipedrive returned success: false');
34  }
35  return json.data as T;
36}
37
38export interface PipedriveDeal {
39  id: number;
40  title: string;
41  value: number;
42  currency: string;
43  stage_id: number;
44  pipeline_id: number;
45  person_name: string;
46  org_name: string;
47  expected_close_date: string;
48  owner_name: string;
49  status: string;
50}
51
52export async function getDeals(
53  status: string = 'open',
54  pipelineId?: number,
55  limit = 100
56) {
57  const params: Record<string, string> = { status, limit: limit.toString() };
58  if (pipelineId) params.pipeline_id = pipelineId.toString();
59  return pipedriveFetch<PipedriveDeal[]>('/deals', {}, params);
60}
61
62export async function createDeal(fields: {
63  title: string;
64  value?: number;
65  pipeline_id?: number;
66  stage_id?: number;
67  person_id?: number;
68  org_id?: number;
69}) {
70  return pipedriveFetch<{ id: number }>('/deals', {
71    method: 'POST',
72    body: JSON.stringify(fields),
73  });
74}
75
76export async function createPerson(fields: {
77  name: string;
78  email?: string[];
79  phone?: string[];
80  org_id?: number;
81}) {
82  return pipedriveFetch<{ id: number }>('/persons', {
83    method: 'POST',
84    body: JSON.stringify(fields),
85  });
86}
87
88export async function createOrganization(name: string) {
89  return pipedriveFetch<{ id: number }>('/organizations', {
90    method: 'POST',
91    body: JSON.stringify({ name }),
92  });
93}
94
95export async function addNote(dealId: number, content: string) {
96  return pipedriveFetch<{ id: number }>('/notes', {
97    method: 'POST',
98    body: JSON.stringify({ deal_id: dealId, content }),
99  });
100}
101
102export async function getStages(pipelineId?: number) {
103  const params: Record<string, string> = {};
104  if (pipelineId) params.pipeline_id = pipelineId.toString();
105  return pipedriveFetch<Array<{ id: number; name: string; pipeline_id: number; order_nr: number }>>(
106    '/stages',
107    {},
108    params
109  );
110}

The core value of a custom Pipedrive integration is a visual deal pipeline that your team or clients can use without needing individual Pipedrive licenses. A Kanban board showing deals organized by stage, with values and close dates visible at a glance, is the canonical display format. Fetch pipeline stages first using GET /v1/stages?pipeline_id={your_pipeline_id} to get the ordered list of stages with their IDs and names. Then fetch deals and group them by stage_id. Display stages as columns in horizontal scroll order matching the Pipedrive pipeline flow. Each deal card should show: deal title, associated person or organization name, deal value formatted as currency using Intl.NumberFormat, the assigned user (owner), and expected close date with a relative indicator (days remaining or days overdue). Color-code the close date: green for 14 or more days away, yellow for 1-13 days, red for past due. Add a pipeline summary header showing the total number of deals and total value per stage — this immediately communicates pipeline health without counting individual cards. The total value for the 'Closed Won' stage over the current month is a key metric for any sales dashboard. For performance, avoid re-fetching all deals on every interaction. Fetch once on page load, store in React state, and update optimistically when users move deals between stages. The Pipedrive API supports deal stage updates via PUT /v1/deals/{id} with a new stage_id — this enables drag-to-move functionality if you want to build it, though it requires deployed testing since the API call works in the WebContainer but drag-and-drop interactions may behave differently across environments.

1// app/api/pipedrive/deals/route.ts
2import { NextResponse } from 'next/server';
3import { getDeals, getStages } from '@/lib/pipedrive';
4
5export async function GET(request: Request) {
6  const { searchParams } = new URL(request.url);
7  const pipelineId = searchParams.get('pipeline_id')
8    ? parseInt(searchParams.get('pipeline_id')!)
9    : undefined;
10  const status = searchParams.get('status') ?? 'open';
11
12  try {
13    const [deals, stages] = await Promise.all([
14      getDeals(status, pipelineId),
15      getStages(pipelineId),
16    ]);
17
18    // Group deals by stage
19    const byStage: Record<number, typeof deals> = {};
20    for (const stage of stages) {
21      byStage[stage.id] = [];
22    }
23    for (const deal of (deals ?? [])) {
24      if (byStage[deal.stage_id]) {
25        byStage[deal.stage_id].push(deal);
26      }
27    }
28
29    return NextResponse.json({
30      stages: stages ?? [],
31      dealsByStage: byStage,
32      totalValue: (deals ?? []).reduce((sum, d) => sum + (d.value ?? 0), 0),
33      currency: deals?.[0]?.currency ?? 'USD',
34    });
35  } catch (error) {
36    const message = error instanceof Error ? error.message : 'Unknown error';
37    return NextResponse.json({ error: message }, { status: 500 });
38  }
39}

Complete the integration by adding two features: creating Pipedrive deals from lead capture form submissions (automating the manual CRM data entry), and exporting Pipedrive data as JSON for analysis or integration with other systems. For deal creation from forms, the workflow creates three connected records in sequence: an organization (the company), a person (the contact), and a deal linked to both. Pipedrive's API requires sequential creation because each resource returns an ID needed for the next: create the organization first, get its ID, create the person with the org_id, get the person's ID, then create the deal with both person_id and org_id. Add a note to the deal with any message or additional context from the form. For JSON export, implement pagination to retrieve all deals rather than just the first page. Pipedrive returns pagination metadata in the additional_data field: pagination.start (current page offset), pagination.limit (items per page), pagination.more_items_in_collection (boolean), and pagination.next_start (next page offset). Loop through all pages until more_items_in_collection is false, accumulating all deals. The export endpoint should accept filter parameters: status (open/won/lost), pipeline_id, start_date and end_date (filtering by expected_close_date or add_time), and user_id (assigned sales rep). Return the full deal array as JSON with a Content-Type: application/json header and a Content-Disposition: attachment; filename=pipedrive-deals.json header to trigger file download from the browser. This covers the popular 'export Pipedrive to JSON' use case: developers and sales managers can schedule exports, download historical data for reporting, or feed Pipedrive data into BI tools like Google Data Studio or Tableau without needing to set up a formal data integration platform.

1// app/api/pipedrive/export/route.ts
2import { NextResponse } from 'next/server';
3
4export async function GET(request: Request) {
5  const token = process.env.PIPEDRIVE_API_TOKEN;
6  if (!token) {
7    return NextResponse.json({ error: 'PIPEDRIVE_API_TOKEN not configured' }, { status: 500 });
8  }
9
10  const { searchParams } = new URL(request.url);
11  const status = searchParams.get('status') ?? 'all_not_deleted';
12  const pipelineId = searchParams.get('pipeline_id') ?? '';
13
14  const allDeals: Record<string, unknown>[] = [];
15  let start = 0;
16  let hasMore = true;
17
18  while (hasMore) {
19    const params = new URLSearchParams({
20      api_token: token,
21      status,
22      limit: '500',
23      start: start.toString(),
24      ...(pipelineId && { pipeline_id: pipelineId }),
25    });
26
27    const res = await fetch(`https://api.pipedrive.com/v1/deals?${params}`);
28    if (!res.ok) break;
29
30    const json = await res.json();
31    if (!json.success || !json.data) break;
32
33    allDeals.push(...json.data);
34
35    const pagination = json.additional_data?.pagination;
36    hasMore = pagination?.more_items_in_collection ?? false;
37    start = pagination?.next_start ?? 0;
38  }
39
40  return new NextResponse(JSON.stringify(allDeals, null, 2), {
41    headers: {
42      'Content-Type': 'application/json',
43      'Content-Disposition': `attachment; filename=pipedrive-deals-${new Date().toISOString().split('T')[0]}.json`,
44    },
45  });
46}