How to Integrate Bolt.new with Freshsales

Log in to your Freshsales account and navigate to your profile settings. Click the avatar or user icon in the top-right corner, then select Settings. In the left sidebar, scroll down to the API Settings section (sometimes listed under 'Integrations & API' depending on your plan level). Your API key is displayed at the bottom of this page — it's a long alphanumeric string. Copy it. You'll also need your Freshsales domain, which is the subdomain portion of your account URL. For example, if you access Freshsales at https://mycompany.freshsales.io, your domain is mycompany. In Bolt.new, open your project and look for the .env or .env.local file in the file tree. If it doesn't exist, create one in the project root. Add your API key and domain as environment variables. In a Next.js project inside Bolt, use the standard process.env pattern for server-side variables — never use the NEXT_PUBLIC_ prefix for API keys, as that would expose them in the client bundle. The Freshsales API uses simple token authentication: every request must include an Authorization header with the value Token token={your_api_key}. There is no OAuth token refresh to manage, no expiry time to track, and no separate client ID/client secret pair. This makes Freshsales one of the simplest CRM APIs to integrate with from a server-side proxy pattern. Test that your credentials are working by prompting Bolt to create a simple test route that fetches your Freshsales account details.

1// .env.local
2FRESHSALES_API_KEY=your_api_key_here
3FRESHSALES_DOMAIN=your_subdomain_here

With your credentials in place, create the core API utility that all Freshsales routes will use. The helper function should accept an endpoint path (e.g., /contacts), an HTTP method, and an optional request body, and return the parsed JSON response. It constructs the full URL using your FRESHSALES_DOMAIN environment variable and adds the Authorization header automatically. This keeps your API routes clean and avoids repeating authentication logic across multiple files. The contacts API is the most commonly used endpoint. GET /api/contacts returns a paginated list of contacts with all CRM fields including name, email, phone, company, lifecycle stage, and — critically — the Freddy AI lead score under the field lead_score. You can filter contacts by various parameters and sort by fields like lead_score to surface your hottest leads first. The sort parameter uses the format sort=lead_score&sort_type=desc. For creating a new contact, POST to /api/contacts with a JSON body containing a contact object. Required fields are first_name and last_name; email and phone are strongly recommended. You can pass custom field values, tag names as an array, and the owner_id to assign the contact to a specific sales rep. The API returns the newly created contact object with its assigned id, which you can use to link subsequent deal creation to this contact. Because all these API calls are outbound HTTPS requests from your server-side Next.js route, they work perfectly in Bolt's WebContainer development preview. You can create, list, and update contacts without deploying your app — the WebContainer can make any outbound HTTP call over HTTPS.

1// lib/freshsales.ts
2export async function freshsalesFetch(
3  endpoint: string,
4  method: 'GET' | 'POST' | 'PUT' | 'DELETE' = 'GET',
5  body?: Record<string, unknown>
6): Promise<Response> {
7  const domain = process.env.FRESHSALES_DOMAIN!;
8  const apiKey = process.env.FRESHSALES_API_KEY!;
9  const url = `https://${domain}.freshsales.io/api${endpoint}`;
10
11  return fetch(url, {
12    method,
13    headers: {
14      Authorization: `Token token=${apiKey}`,
15      'Content-Type': 'application/json',
16    },
17    ...(body ? { body: JSON.stringify(body) } : {}),
18  });
19}
20
21// app/api/freshsales/contacts/route.ts
22import { NextRequest, NextResponse } from 'next/server';
23import { freshsalesFetch } from '@/lib/freshsales';
24
25export async function GET() {
26  const response = await freshsalesFetch(
27    '/contacts?sort=lead_score&sort_type=desc&per_page=50'
28  );
29  if (!response.ok) {
30    return NextResponse.json({ error: 'Freshsales API error' }, { status: response.status });
31  }
32  const data = await response.json();
33  const contacts = (data.contacts ?? []).map((c: Record<string, unknown>) => ({
34    id: c.id,
35    firstName: c.first_name,
36    lastName: c.last_name,
37    email: c.email,
38    company: (c.company as Record<string, unknown>)?.name ?? '',
39    leadScore: c.lead_score ?? 0,
40    lastContacted: c.last_contacted_time,
41  }));
42  return NextResponse.json({ contacts, total: data.meta?.total_pages });
43}
44
45export async function POST(request: NextRequest) {
46  const body = await request.json();
47  const response = await freshsalesFetch('/contacts', 'POST', { contact: body });
48  if (!response.ok) {
49    const err = await response.json();
50    return NextResponse.json({ error: err }, { status: response.status });
51  }
52  const data = await response.json();
53  return NextResponse.json({ contact: data.contact });
54}

The Deals API follows the same authentication pattern as Contacts. GET /api/deals returns open deals with fields including name, amount, expected_close, deal_stage (an object with id and name), owner, and associated_contacts. You can filter by pipeline with the filter_type parameter and sort by amount, expected_close, or updated_at. Deal stages in Freshsales are configured per pipeline under Settings → Deal Management → Pipelines. Each stage has a numeric id and a string name. When you fetch deals, the deal_stage object tells you where in the funnel each deal currently sits. To move a deal to a new stage, send a PUT request to /api/deals/{id} with a body containing deal: { deal_stage_id: newStageId }. For creating deals, POST to /api/deals with a deal object containing name, amount, expected_close (YYYY-MM-DD format), deal_stage_id, and optionally contacts: [{ id: contactId }] to associate the deal with an existing contact. You can also pass owner_id to assign it to a specific sales rep. When building the dashboard UI in Bolt, describe the kanban layout you want in a Bolt chat prompt. A typical sales dashboard groups deals in columns by stage name, shows total deal value per column, and color-codes cards by expected close date (red for overdue, yellow for this month, green for future). Bolt can generate this layout as a React component using the data returned from your /api/freshsales/deals route. All data fetching happens server-side, so there are no CORS issues — the WebContainer's outbound HTTP works without restriction for these server-to-server calls.

1// app/api/freshsales/deals/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { freshsalesFetch } from '@/lib/freshsales';
4
5export async function GET() {
6  const response = await freshsalesFetch(
7    '/deals?filter_type=open&sort=expected_close&sort_type=asc&per_page=100'
8  );
9  if (!response.ok) {
10    return NextResponse.json({ error: 'Freshsales API error' }, { status: response.status });
11  }
12  const data = await response.json();
13  const deals = (data.deals ?? []).map((d: Record<string, unknown>) => ({
14    id: d.id,
15    name: d.name,
16    amount: d.amount,
17    expectedClose: d.expected_close,
18    stage: (d.deal_stage as Record<string, unknown>)?.name ?? 'Unknown',
19    stageId: (d.deal_stage as Record<string, unknown>)?.id,
20    ownerName: (d.owner as Record<string, unknown>)?.name ?? '',
21    contacts: (d.contacts as Array<Record<string, unknown>>)?.map((c) => c.display_name) ?? [],
22  }));
23  return NextResponse.json({ deals });
24}
25
26export async function POST(request: NextRequest) {
27  const { name, amount, expectedClose, stageId, contactId } = await request.json();
28  const body = {
29    deal: {
30      name,
31      amount,
32      expected_close: expectedClose,
33      deal_stage_id: stageId,
34      ...(contactId ? { contacts: [{ id: contactId }] } : {}),
35    },
36  };
37  const response = await freshsalesFetch('/deals', 'POST', body);
38  if (!response.ok) {
39    const err = await response.json();
40    return NextResponse.json({ error: err }, { status: response.status });
41  }
42  const data = await response.json();
43  return NextResponse.json({ deal: data.deal });
44}

One of the most practical Freshsales integrations for Bolt apps is automatic lead capture: when a user fills out a contact form, demo request form, or waitlist signup in your Bolt app, the submission is immediately forwarded to Freshsales as a new contact and lead. This keeps the sales team working with up-to-date data without any manual CSV imports. The implementation uses a server-side POST route that receives form data from the React component, validates the required fields, and then calls the Freshsales Contacts API to create or upsert the contact. Freshsales supports upsert via a POST to /api/contacts/upsert — if a contact with the same email already exists, it updates them instead of creating a duplicate. This is important for form-heavy use cases where the same person might submit multiple times. You can enrich the contact record at creation time by passing additional fields: lifecycle_stage (one of Lead, Marketing Qualified Lead, Sales Qualified Lead, etc.), tags as an array of strings (e.g., ['bolt-landing-page', 'demo-request']), and any custom fields your sales team has configured. If you know the source (UTM parameters, referrer page), store it in a custom field so reps know where each lead came from. Test the full form-to-CRM flow in Bolt's development preview — since the form submission fires an outbound POST to Freshsales' API, it works without deployment. Check your Freshsales contacts list after submitting the form to confirm the lead was created with all the right fields populated.

1// app/api/freshsales/contacts/upsert/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { freshsalesFetch } from '@/lib/freshsales';
4
5export async function POST(request: NextRequest) {
6  const { firstName, lastName, email, phone, company } = await request.json();
7
8  if (!email || !firstName) {
9    return NextResponse.json(
10      { error: 'firstName and email are required' },
11      { status: 400 }
12    );
13  }
14
15  const body = {
16    contact: {
17      first_name: firstName,
18      last_name: lastName ?? '',
19      email,
20      mobile_number: phone ?? '',
21      company: { name: company ?? '' },
22      lifecycle_stage: 1, // 1 = Lead
23      tags: ['bolt-app-lead'],
24    },
25    unique_identifier: { email },
26  };
27
28  const response = await freshsalesFetch('/contacts/upsert', 'POST', body);
29  if (!response.ok) {
30    const err = await response.json();
31    return NextResponse.json({ error: err }, { status: response.status });
32  }
33  const data = await response.json();
34  return NextResponse.json({
35    contact: data.contact,
36    wasCreated: response.status === 201,
37  });
38}

Freshsales can send real-time notifications to your app when contacts are updated, deals move between stages, tasks are completed, or custom events occur. Unlike the outbound API calls in the previous steps — which work fine in Bolt's WebContainer — webhooks are incoming HTTP requests from Freshsales' servers to your app. Bolt's WebContainer runs inside a browser tab and has no public IP address or DNS hostname, so Freshsales cannot reach it. You must deploy your app first. Deploy your app to Netlify or Vercel using Bolt's export workflow. Once you have a stable public URL (e.g., https://my-crm-app.netlify.app), create the webhook handler. In Freshsales, navigate to Settings → Integrations → Webhooks → Create Webhook. Enter your webhook URL (https://my-crm-app.netlify.app/api/freshsales/webhook), select the events to subscribe to — common choices are Contact Updated, Deal Stage Changed, and Task Completed — and click Save. Your webhook handler should validate requests are genuinely from Freshsales using the X-Freshsales-Signature header (if your plan provides it), parse the JSON payload, and respond with HTTP 200 within 10 seconds. The payload structure varies by event type: contact events include a contact object with all fields, deal events include a deal object with the old and new stage IDs. Add FRESHSALES_WEBHOOK_SECRET to your hosting platform's environment variables before enabling the webhook. Set environment variables in Netlify under Site settings → Environment variables or in Vercel under Project settings → Environment variables.

1// app/api/freshsales/webhook/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4export async function POST(request: NextRequest) {
5  let payload: Record<string, unknown>;
6
7  try {
8    payload = await request.json();
9  } catch {
10    return NextResponse.json({ error: 'Invalid JSON' }, { status: 400 });
11  }
12
13  const eventType = payload.event_type as string;
14
15  if (eventType === 'deal_stage_changed') {
16    const deal = payload.deal as Record<string, unknown>;
17    console.log(`Deal stage changed: ${deal.name}`);
18    // Add your database update or notification logic here
19  }
20
21  if (eventType === 'contact_updated') {
22    const contact = payload.contact as Record<string, unknown>;
23    console.log(`Contact updated: ${contact.email}`);
24    // Add your sync or notification logic here
25  }
26
27  return NextResponse.json({ received: true });
28}