How to Integrate Freshsales with V0

Start by prompting V0 to generate the frontend components for your Freshsales integration. V0 produces high-quality data-dense CRM interfaces: kanban pipeline boards, sortable data tables, contact cards, deal detail panels, and activity timelines. Describing the Freshsales data structure in your V0 prompt helps it generate components with the correct field bindings. Key Freshsales data shapes to reference in your V0 prompts: Leads have first_name, last_name, email, mobile_number, lead_source, lead_stage, owner_id, and lead_score. Deals have name, deal_stage_id, amount, expected_close, deal_type, and associated_contacts. Contacts have first_name, last_name, email, mobile_number, company, and job_title. Including these field names helps V0 generate TypeScript interfaces and component props that match what your API route will return. For CRM dashboards specifically, V0 excels at generating kanban boards for deal pipelines, but the drag-and-drop functionality requires a library like @hello-pangea/dnd (the maintained fork of react-beautiful-dnd) or @dnd-kit/core. Ask V0 to use one of these libraries rather than implementing drag-and-drop from scratch. V0 knows both libraries and can generate the correct drag-and-drop setup. One important V0-specific consideration for CRM dashboards: V0 may generate the pipeline board with hardcoded stage names and counts. Make sure to ask V0 to load both the deals and the stage configuration dynamically from your API routes, since Freshsales stage names are configurable per account and may not match generic labels like 'New' or 'In Progress'.

Create a server-side API route that fetches deal data from Freshsales. In your V0 project, create app/api/freshsales/route.ts. Freshsales's API uses your API key in a Authorization header and your account domain as part of the base URL. Freshsales authentication uses the pattern: Authorization: Token token=YOUR_API_KEY. Note the specific format — 'Token token=' followed by your API key. This is different from the standard Bearer token format used by most APIs. Getting this header exactly right is critical; the wrong format returns a 401 even with a valid key. The Freshsales API base URL is https://YOUR_DOMAIN.myfreshworks.com/crm/sales/api. Your domain is the subdomain part of your Freshsales URL. For example, if you access Freshsales at https://mycompany.myfreshworks.com, your domain is 'mycompany'. Store this as FRESHSALES_DOMAIN in Vercel environment variables. Freshsales uses a filter-based search API for listing records. To fetch all deals, you use the POST /deals/filter endpoint with a filter body, or GET /deals for paginated lists. The filter endpoint is more powerful for custom queries — you can filter by stage, owner, date range, or any custom field. For a simple deals list, GET /deals?page=1&per_page=50 is the simplest approach. Freshsales API pagination uses page and per_page query parameters. The maximum per_page is typically 100 for most endpoints. The response includes a meta object with total_pages and total_count, making it straightforward to implement pagination in your UI.

1import { NextRequest, NextResponse } from 'next/server';
2
3const FRESHSALES_DOMAIN = process.env.FRESHSALES_DOMAIN;
4const FRESHSALES_API_KEY = process.env.FRESHSALES_API_KEY;
5
6interface FreshsalesDeal {
7  id: number;
8  name: string;
9  amount: number;
10  deal_stage_id: number;
11  expected_close: string | null;
12  created_at: string;
13  updated_at: string;
14  owner_id: number;
15}
16
17interface FreshsalesResponse {
18  deals: FreshsalesDeal[];
19  meta: {
20    total_pages: number;
21    total_count: number;
22  };
23}
24
25export async function GET(request: NextRequest) {
26  try {
27    if (!FRESHSALES_DOMAIN || !FRESHSALES_API_KEY) {
28      return NextResponse.json(
29        { error: 'Freshsales configuration missing' },
30        { status: 500 }
31      );
32    }
33
34    const { searchParams } = new URL(request.url);
35    const page = searchParams.get('page') || '1';
36    const perPage = searchParams.get('per_page') || '50';
37
38    const url = new URL(
39      `https://${FRESHSALES_DOMAIN}.myfreshworks.com/crm/sales/api/deals`
40    );
41    url.searchParams.set('page', page);
42    url.searchParams.set('per_page', perPage);
43    url.searchParams.set('include', 'owner,contact,deal_stage');
44
45    const response = await fetch(url.toString(), {
46      headers: {
47        Authorization: `Token token=${FRESHSALES_API_KEY}`,
48        'Content-Type': 'application/json',
49      },
50    });
51
52    if (!response.ok) {
53      const errorText = await response.text();
54      console.error('Freshsales API error:', errorText);
55      return NextResponse.json(
56        { error: `Freshsales API error: ${response.status}` },
57        { status: response.status }
58      );
59    }
60
61    const data: FreshsalesResponse = await response.json();
62
63    return NextResponse.json({
64      deals: data.deals || [],
65      meta: data.meta,
66    });
67  } catch (error) {
68    console.error('Freshsales route error:', error);
69    return NextResponse.json(
70      { error: 'Failed to fetch Freshsales deals' },
71      { status: 500 }
72    );
73  }
74}

Extend your integration with routes for creating and updating CRM records. A read-only CRM dashboard has limited value — the real utility comes from being able to create leads from web forms, update deal stages, log activities, and assign records to team members directly from your V0 app. For creating leads (common for contact forms and landing pages built with V0), create app/api/freshsales/leads/route.ts with a POST handler. Freshsales's lead creation endpoint is POST /leads with a JSON body containing the lead's details wrapped in a lead object. Required fields are first_name and last_name or email — at least one contact identifier is needed. For updating deal stages (for the kanban pipeline drag-and-drop), create a PUT handler for individual deals. Freshsales updates use PUT /deals/{id} with a deal object in the body containing only the fields you want to change. You do not need to send the full deal object — partial updates work correctly. A common integration pattern for real estate use cases: embed a Freshsales lead capture form on a V0 landing page. When the form is submitted, the Next.js API route creates a lead in Freshsales with the form data, sends a confirmation email via an email service, and redirects the user to a thank-you page. V0 can generate the form component with the correct fetch call structure. Freshsales webhooks let you receive real-time notifications when CRM records change — when a new lead comes in, when a deal closes, or when a contact is updated. For webhook integration, create a route at app/api/freshsales/webhook/route.ts that receives POST events from Freshsales and updates your app's state or database accordingly.

1import { NextRequest, NextResponse } from 'next/server';
2
3const FRESHSALES_DOMAIN = process.env.FRESHSALES_DOMAIN;
4const FRESHSALES_API_KEY = process.env.FRESHSALES_API_KEY;
5
6export async function POST(request: NextRequest) {
7  try {
8    const body = await request.json();
9    const { firstName, lastName, email, phone, company, leadSource } = body;
10
11    if (!email && !firstName) {
12      return NextResponse.json(
13        { error: 'At least one of email or first name is required' },
14        { status: 400 }
15      );
16    }
17
18    const leadData = {
19      lead: {
20        first_name: firstName || '',
21        last_name: lastName || '',
22        email: email || '',
23        mobile_number: phone || '',
24        company: { name: company || '' },
25        lead_source_id: null, // Map leadSource to your Freshsales source IDs
26        custom_field: {
27          lead_source_label: leadSource || '',
28        },
29      },
30    };
31
32    const response = await fetch(
33      `https://${FRESHSALES_DOMAIN}.myfreshworks.com/crm/sales/api/leads`,
34      {
35        method: 'POST',
36        headers: {
37          Authorization: `Token token=${FRESHSALES_API_KEY}`,
38          'Content-Type': 'application/json',
39        },
40        body: JSON.stringify(leadData),
41      }
42    );
43
44    if (!response.ok) {
45      const errorData = await response.text();
46      console.error('Freshsales create lead error:', errorData);
47      return NextResponse.json(
48        { error: 'Failed to create lead in Freshsales' },
49        { status: response.status }
50      );
51    }
52
53    const newLead = await response.json();
54    return NextResponse.json({ lead: newLead.lead }, { status: 201 });
55  } catch (error) {
56    console.error('Freshsales leads POST error:', error);
57    return NextResponse.json(
58      { error: 'Internal server error' },
59      { status: 500 }
60    );
61  }
62}

Your Freshsales API routes require two environment variables: your API key and your Freshsales domain. Both must be available in Vercel's environment for your serverless functions to authenticate with Freshsales. Go to Vercel Dashboard → your project → Settings → Environment Variables and add: FRESHSALES_API_KEY: Your Freshsales API key. To find it, log into Freshsales and go to Admin Settings (gear icon) → API Settings. Your API key is shown on that page. It is a long alphanumeric string. Do not add any prefix — this is a server-only secret that must never reach the browser. It grants full API access to your Freshsales account data. FRESHSALES_DOMAIN: Just the subdomain portion of your Freshsales URL. If you access Freshsales at https://mycompany.myfreshworks.com, enter only mycompany (without https://, without .myfreshworks.com). This is combined with the Freshsales base URL in your API route code. Set both variables for Production, Preview, and Development environments. Click Save after adding each. For local development, add both to your .env.local file. After saving, push a commit to trigger a Vercel redeployment. The new environment variables are not available in previously built functions — a fresh deployment is required. Once deployed, verify the integration by loading your CRM dashboard and checking that deals appear.

Test the full Freshsales integration by navigating to your deployed V0 app and verifying that CRM data loads and mutations work correctly. Freshsales test data: in your Freshsales account, create a few test leads, deals, and contacts if your account is empty. Freshsales's free trial comes pre-populated with sample data, so you may already have records to work with. Navigate to the deals page in your V0 app. The deals table should populate with your Freshsales deals within 1-2 seconds. Check the Vercel function logs (Vercel Dashboard → project → Functions) to verify the Freshsales API is responding with 200 status codes. If you see 401 errors, your API key or domain is incorrect. If you see empty data with 200 responses, verify you have active deals in Freshsales. Test lead creation by submitting the New Lead form. After submission, immediately check Freshsales → Leads to confirm the record was created with the correct data. If the lead appears but some fields are wrong, adjust the field mapping in your API route's lead object structure. For real-time updates — receiving notifications when a deal is won or a lead is assigned — configure Freshsales webhooks in Admin Settings → Integrations → Webhooks. Add your Vercel deployment URL as the webhook endpoint (e.g., https://your-app.vercel.app/api/freshsales/webhook). Select the events you want (deal updated, lead created, contact updated). Your webhook route will receive POST requests with event payloads whenever these events occur in Freshsales. For complex Freshsales integrations with custom fields, multi-stage pipeline automation, and real-time sync between Freshsales and other data sources, RapidDev's team can help design and build the full integration architecture for your V0 app.