How to Integrate Insightly with V0

Insightly's API key is found in your user profile settings. It is a unique key tied to your user account and grants the same access permissions as your Insightly user role. Log into your Insightly account at app.insightly.com. Click on your profile avatar or name in the top-right corner of the interface. Select 'User Settings' from the dropdown menu. In your User Settings page, scroll down to find the 'API Key' section. Your API key is displayed there as a long alphanumeric string. Click the copy icon or select the key text and copy it. Insightly uses HTTP Basic Authentication with the API key as the username and an empty string as the password. Before using the key in your API route, you need to Base64-encode the string 'YOUR_API_KEY:' (with the colon but without quotes, and with an empty string after the colon). The resulting Base64 string is what goes in the Authorization header as 'Basic {base64string}'. You can test your credentials quickly using curl: curl -H 'Authorization: Basic {base64}' https://api.insightly.com/v3.1/contacts. If it returns a JSON array, your authentication is working. Insightly's API base URL depends on your account's data region. North American accounts use https://api.insightly.com. European accounts may use a different subdomain. Check your account region in Insightly's documentation or contact Insightly support if standard API calls return 404. Note that Insightly API access is included on all paid plans. Free plan accounts may have limited or no API access.

Store your Insightly API key in Vercel's environment variables. Your API route will Base64-encode it at runtime, so you store the raw key value rather than the encoded string. Open your Vercel Dashboard, navigate to your project, click 'Settings', and select 'Environment Variables'. Add: INSIGHTLY_API_KEY: Your raw Insightly API key. This is a secret — set it for Production, Preview, and Development environments. Do not add a NEXT_PUBLIC_ prefix. Save the variable and trigger a redeployment. For local development, add the same variable to your .env.local file. Optionally, if your account uses the European data region, also add INSIGHTLY_API_BASE_URL=https://api.na1.insightly.com or the appropriate regional URL for your account.

1# .env.local — local development only, excluded from Git
2INSIGHTLY_API_KEY=your_insightly_api_key_here
3# Optional: if your account uses EU region
4# INSIGHTLY_API_BASE_URL=https://api.eu1.insightly.com

Create Next.js API routes for contacts and opportunities. The key detail for Insightly is the Basic Auth header format — your route must Base64-encode the API key with a trailing colon before sending it. Create app/api/insightly/contacts/route.ts. The contacts endpoint is GET https://api.insightly.com/v3.1/contacts. It supports query parameters including top (page size, max 500), skip (for pagination), and $filter (OData filter expression) and $orderby for sorting. Insightly returns contacts with nested arrays for email addresses and phone numbers (EMAIL_ADDRESSES array containing objects with EMAIL_ADDRESS and EMAIL_TYPE, and PHONE_NUMBERS array containing objects with PHONE_NUMBER and PHONE_TYPE). Your route should flatten these for easier component consumption. The opportunities endpoint is GET https://api.insightly.com/v3.1/opportunities with similar pagination support. Filter by STATE='open' using OData syntax: $filter=STATE eq 'open'. Each opportunity includes OPPORTUNITY_VALUE, PROBABILITY, CLOSE_DATE, STAGE_ORDER_NUMBER, and PIPELINE_ID along with basic metadata. Insightly also has a pipeline stages endpoint (GET /v3.1/OpportunityCategories) and a pipelines endpoint (GET /v3.1/Pipelines) to get the stages within each pipeline. Fetch these once to map stage order numbers to human-readable stage names.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface InsightlyEmailAddress {
4  EMAIL_ADDRESS: string;
5  EMAIL_TYPE: string;
6}
7
8interface InsightlyPhoneNumber {
9  PHONE_NUMBER: string;
10  PHONE_TYPE: string;
11}
12
13interface InsightlyContact {
14  CONTACT_ID: number;
15  FIRST_NAME: string;
16  LAST_NAME: string;
17  ORGANISATION_NAME: string | null;
18  TITLE: string | null;
19  EMAIL_ADDRESSES: InsightlyEmailAddress[];
20  PHONE_NUMBERS: InsightlyPhoneNumber[];
21  DATE_UPDATED_UTC: string;
22}
23
24function getInsightlyAuthHeader(apiKey: string): string {
25  // Insightly Basic Auth: Base64-encode 'apiKey:' (key + colon, empty password)
26  return 'Basic ' + Buffer.from(`${apiKey}:`).toString('base64');
27}
28
29export async function GET(request: NextRequest) {
30  const apiKey = process.env.INSIGHTLY_API_KEY;
31  const apiBase =
32    process.env.INSIGHTLY_API_BASE_URL || 'https://api.insightly.com';
33
34  if (!apiKey) {
35    return NextResponse.json(
36      { error: 'Insightly configuration missing' },
37      { status: 500 }
38    );
39  }
40
41  const { searchParams } = new URL(request.url);
42  const search = searchParams.get('search') || '';
43
44  const contactsUrl = new URL(`${apiBase}/v3.1/contacts`);
45  contactsUrl.searchParams.set('top', '200');
46  contactsUrl.searchParams.set('$orderby', 'LAST_NAME asc');
47  if (search) {
48    contactsUrl.searchParams.set(
49      '$filter',
50      `LAST_NAME eq '${search}' or FIRST_NAME eq '${search}'`
51    );
52  }
53
54  try {
55    const response = await fetch(contactsUrl.toString(), {
56      headers: {
57        Authorization: getInsightlyAuthHeader(apiKey),
58        'Content-Type': 'application/json',
59      },
60      next: { revalidate: 120 },
61    });
62
63    if (!response.ok) {
64      const error = await response.text();
65      console.error('Insightly API error:', error);
66      return NextResponse.json(
67        { error: `Insightly returned ${response.status}` },
68        { status: response.status }
69      );
70    }
71
72    const contacts: InsightlyContact[] = await response.json();
73
74    const transformed = contacts.map((c) => ({
75      id: c.CONTACT_ID,
76      firstName: c.FIRST_NAME || '',
77      lastName: c.LAST_NAME || '',
78      fullName: `${c.FIRST_NAME || ''} ${c.LAST_NAME || ''}`.trim(),
79      company: c.ORGANISATION_NAME || '',
80      title: c.TITLE || '',
81      email:
82        c.EMAIL_ADDRESSES?.find((e) => e.EMAIL_TYPE === 'WORK')?.EMAIL_ADDRESS ||
83        c.EMAIL_ADDRESSES?.[0]?.EMAIL_ADDRESS ||
84        '',
85      phone:
86        c.PHONE_NUMBERS?.find((p) => p.PHONE_TYPE === 'WORK')?.PHONE_NUMBER ||
87        c.PHONE_NUMBERS?.[0]?.PHONE_NUMBER ||
88        '',
89      updatedAt: c.DATE_UPDATED_UTC,
90    }));
91
92    return NextResponse.json({ contacts: transformed, total: transformed.length });
93  } catch (error) {
94    console.error('Insightly contacts fetch failed:', error);
95    return NextResponse.json(
96      { error: 'Failed to fetch contacts' },
97      { status: 500 }
98    );
99  }
100}

With the Insightly API routes returning data, prompt V0 to generate the CRM dashboard components. Sales dashboards need clear visual hierarchy — pipeline value should be prominent, stage groupings should be obvious, and overdue or high-priority items should stand out. First, review the JSON output of your /api/insightly/contacts and /api/insightly/opportunities routes to confirm the field names and data structure. Reference these exact field names in your V0 prompts. For a pipeline dashboard, describe the column layout (one column per pipeline stage), the card content (opportunity name, value, expected close date, owner), and the color coding scheme (green for on-track, yellow for closing soon, red for overdue). Tell V0 the stage names used in your Insightly pipeline. For a contact directory, describe the table columns, sort behavior, and search functionality. Ask V0 to add pagination if your contact list exceeds 50-100 entries, since rendering hundreds of rows at once slows the browser. Ask V0 to add summary metric cards at the top of the dashboard: total pipeline value, number of open opportunities, opportunities closing this month, and win rate. These high-level numbers are usually what executives and managers look at first.

Create the opportunities API route to complete the CRM dashboard. Opportunities in Insightly represent deals in your sales pipeline, each with a value, close date, stage, and probability. Create app/api/insightly/opportunities/route.ts. The opportunities endpoint is GET https://api.insightly.com/v3.1/opportunities. Useful query parameters include $filter=STATE eq 'open' to show only open deals, $top for page size, and $orderby=CLOSE_DATE asc for sorting by close date. Each Insightly opportunity includes OPPORTUNITY_ID, OPPORTUNITY_NAME, OPPORTUNITY_VALUE, OPPORTUNITY_STATE (open/won/lost), CLOSE_DATE, PROBABILITY, RESPONSIBLE_USER_ID, and PIPELINE_ID. The STAGE_ORDER_NUMBER field indicates the position within the pipeline (0 = first stage, higher numbers = later stages). For a complete pipeline view, you also want the stage name rather than just the order number. Fetch pipeline stages from GET /v3.1/Pipelines/{pipelineId}/Stages to get a mapping of stage order numbers to stage names. You can either cache this mapping in your API route or fetch it on each request since pipeline structures rarely change. For agencies and sales teams who want to build more complex Insightly integrations — such as syncing opportunity wins to trigger onboarding workflows, automatically creating Insightly contacts from form submissions, or building a two-way sync with another CRM — RapidDev can help design the full integration architecture.

1import { NextResponse } from 'next/server';
2
3interface InsightlyOpportunity {
4  OPPORTUNITY_ID: number;
5  OPPORTUNITY_NAME: string;
6  OPPORTUNITY_VALUE: number | null;
7  OPPORTUNITY_STATE: string;
8  CLOSE_DATE: string | null;
9  PROBABILITY: number | null;
10  RESPONSIBLE_USER_ID: number | null;
11  STAGE_ORDER_NUMBER: number;
12  PIPELINE_ID: number | null;
13  OWNER_USER_ID: number;
14  RESPONSIBLE_USER_NAME?: string;
15}
16
17export async function GET() {
18  const apiKey = process.env.INSIGHTLY_API_KEY;
19  const apiBase =
20    process.env.INSIGHTLY_API_BASE_URL || 'https://api.insightly.com';
21
22  if (!apiKey) {
23    return NextResponse.json(
24      { error: 'Insightly configuration missing' },
25      { status: 500 }
26    );
27  }
28
29  const authHeader =
30    'Basic ' + Buffer.from(`${apiKey}:`).toString('base64');
31
32  const oppsUrl = new URL(`${apiBase}/v3.1/opportunities`);
33  oppsUrl.searchParams.set('$filter', "OPPORTUNITY_STATE eq 'Open'");
34  oppsUrl.searchParams.set('$top', '200');
35  oppsUrl.searchParams.set('$orderby', 'CLOSE_DATE asc');
36
37  try {
38    const response = await fetch(oppsUrl.toString(), {
39      headers: {
40        Authorization: authHeader,
41        'Content-Type': 'application/json',
42      },
43      next: { revalidate: 120 },
44    });
45
46    if (!response.ok) {
47      const error = await response.text();
48      console.error('Insightly opportunities error:', error);
49      return NextResponse.json(
50        { error: `Insightly returned ${response.status}` },
51        { status: response.status }
52      );
53    }
54
55    const opportunities: InsightlyOpportunity[] = await response.json();
56
57    const transformed = opportunities.map((o) => ({
58      id: o.OPPORTUNITY_ID,
59      name: o.OPPORTUNITY_NAME,
60      value: o.OPPORTUNITY_VALUE ?? 0,
61      state: o.OPPORTUNITY_STATE.toLowerCase(),
62      closeDate: o.CLOSE_DATE,
63      isOverdue: o.CLOSE_DATE
64        ? new Date(o.CLOSE_DATE) < new Date()
65        : false,
66      probability: o.PROBABILITY ?? 0,
67      stageOrder: o.STAGE_ORDER_NUMBER,
68      pipelineId: o.PIPELINE_ID,
69    }));
70
71    const totalValue = transformed.reduce((sum, o) => sum + o.value, 0);
72
73    return NextResponse.json({
74      opportunities: transformed,
75      total: transformed.length,
76      totalValue,
77    });
78  } catch (error) {
79    console.error('Insightly opportunities fetch failed:', error);
80    return NextResponse.json(
81      { error: 'Failed to fetch opportunities' },
82      { status: 500 }
83    );
84  }
85}