How to Integrate Bolt.new with Insightly

Insightly uses HTTP Basic authentication with your API key as the username and an empty password. The Basic auth header is constructed by Base64-encoding the string 'YOUR_API_KEY:' (note the trailing colon with nothing after it, representing an empty password). This unusual format is specific to Insightly and differs from standard Basic auth where both username and password are typically non-empty. To get your API key, log into Insightly and click your user avatar in the top-right corner, then select 'User Settings.' Scroll to the API section. You will see your personal API key — a 36-character UUID-format string (groups of hexadecimal characters separated by hyphens, like 12345678-abcd-1234-abcd-123456789abc). Copy it. The API key provides the same level of access as your Insightly user account. If you are an administrator, the key gives admin-level access. For production integrations, consider creating a dedicated API user with limited permissions if your plan supports multiple users. Insightly's API base URL is https://api.insightly.com/v3.1 for most accounts. Enterprise plans on dedicated infrastructure use different base URLs — check your Insightly Settings under the API section for your specific instance URL. Store this as INSIGHTLY_BASE_URL in .env so you can easily change it if needed. Construct the Basic auth header in Node.js as follows: take the API key string, add a colon at the end (key + ':'), Base64-encode the entire string, and prefix it with 'Basic '. This is different from standard Basic auth — the 'password' field is intentionally empty. Store the raw API key in .env as INSIGHTLY_API_KEY and construct the header in your service module at runtime. Outbound API calls to api.insightly.com work in Bolt's WebContainer preview since they use standard HTTPS. You can test the full integration — fetching contacts, creating opportunities — directly in the Bolt preview without deploying first.

1# .env
2# Insightly API key — server-side only, never NEXT_PUBLIC_
3# Get from Insightly: User avatar → User Settings → API section
4# Format: UUID-style string (12345678-abcd-1234-abcd-123456789abc)
5INSIGHTLY_API_KEY=your-api-key-here
6
7# Insightly API base URL — usually https://api.insightly.com/v3.1
8# Enterprise customers may have a custom base URL — verify in Settings → API
9INSIGHTLY_BASE_URL=https://api.insightly.com/v3.1

Create the Insightly API service module with typed helper functions for the most common operations, and build Next.js API routes for contacts, organizations, opportunities, and projects. Insightly's REST API v3.1 is RESTful but uses uppercase field names (FIRST_NAME, LAST_NAME, EMAIL_ADDRESS, OPPORTUNITY_NAME) rather than the camelCase or snake_case common in newer APIs. This is a holdover from the platform's older architecture — always check the Insightly API documentation for exact field names, as the capitalization matters. The key object types and their primary fields are: Contacts (CONTACT_ID, FIRST_NAME, LAST_NAME, EMAIL_ADDRESS, PHONE, ORGANISATION_ID), Organisations (ORGANISATION_ID, ORGANISATION_NAME, PHONE, WEBSITE), Opportunities (OPPORTUNITY_ID, OPPORTUNITY_NAME, OPPORTUNITY_STATE, BID_AMOUNT, CLOSE_DATE, PIPELINE_ID, STAGE_ID, ORGANISATION_ID, RESPONSIBLE_USER_ID), and Projects (PROJECT_ID, PROJECT_NAME, STATUS, STARTED_DATE, COMPLETED_DATE, RESPONSIBLE_USER_ID). Insightly's pagination uses skip and top parameters rather than page numbers: GET /Contacts?skip=0&top=50 returns the first 50 contacts. For large datasets, increment skip by top to retrieve subsequent pages. Links between objects use a LINKS array in the response and request bodies: [{ 'LINK_OBJECT_NAME': 'Contact', 'LINK_OBJECT_ID': 12345, 'ROLE': 'Responsible' }]. This linking mechanism connects contacts to opportunities, opportunities to projects, and tasks to any object type. Understanding links is essential for building the combined CRM + project dashboard that surfaces Insightly's unique value.

1// lib/insightly.ts
2function getInsightlyAuth(): string {
3  const key = process.env.INSIGHTLY_API_KEY;
4  if (!key) throw new Error('INSIGHTLY_API_KEY not configured');
5  // Insightly Basic auth: Base64 of 'api_key:' (empty password)
6  return Buffer.from(`${key}:`).toString('base64');
7}
8
9const BASE = () => {
10  const url = process.env.INSIGHTLY_BASE_URL ?? 'https://api.insightly.com/v3.1';
11  return url;
12};
13
14async function insightlyFetch<T>(path: string, options: RequestInit = {}): Promise<T> {
15  const res = await fetch(`${BASE()}${path}`, {
16    ...options,
17    headers: {
18      Authorization: `Basic ${getInsightlyAuth()}`,
19      'Content-Type': 'application/json',
20      Accept: 'application/json',
21      ...options.headers,
22    },
23  });
24
25  if (!res.ok) {
26    const body = await res.text();
27    throw Object.assign(new Error(`Insightly API error: ${res.status}`), {
28      status: res.status,
29      body,
30    });
31  }
32
33  return res.json();
34}
35
36export interface InsightlyContact {
37  CONTACT_ID?: number;
38  FIRST_NAME: string;
39  LAST_NAME: string;
40  EMAIL_ADDRESS?: string;
41  PHONE?: string;
42  ORGANISATION_ID?: number;
43}
44
45export interface InsightlyOpportunity {
46  OPPORTUNITY_ID?: number;
47  OPPORTUNITY_NAME: string;
48  OPPORTUNITY_STATE?: string;
49  BID_AMOUNT?: number;
50  CLOSE_DATE?: string;
51  ORGANISATION_ID?: number;
52  PIPELINE_ID?: number;
53  STAGE_ID?: number;
54}
55
56export async function getContacts(skip = 0, top = 50) {
57  return insightlyFetch<InsightlyContact[]>(`/Contacts?skip=${skip}&top=${top}`);
58}
59
60export async function createContact(fields: InsightlyContact) {
61  return insightlyFetch<InsightlyContact>('/Contacts', {
62    method: 'POST',
63    body: JSON.stringify(fields),
64  });
65}
66
67export async function createOrganization(name: string) {
68  return insightlyFetch<{ ORGANISATION_ID: number }>('/Organisations', {
69    method: 'POST',
70    body: JSON.stringify({ ORGANISATION_NAME: name }),
71  });
72}
73
74export async function getOpportunities(state?: string) {
75  const filter = state ? `?opportunity_state=${state}` : '';
76  return insightlyFetch<InsightlyOpportunity[]>(`/Opportunities${filter}`);
77}
78
79export async function createOpportunity(fields: InsightlyOpportunity) {
80  return insightlyFetch<InsightlyOpportunity>('/Opportunities', {
81    method: 'POST',
82    body: JSON.stringify(fields),
83  });
84}
85
86export async function getProjects(status?: string) {
87  const filter = status ? `?status=${status}` : '';
88  return insightlyFetch<Array<{ PROJECT_ID: number; PROJECT_NAME: string; STATUS: string }>>(
89    `/Projects${filter}`
90  );
91}

Insightly's unique value proposition is linking opportunities (sales) to projects (delivery). Build a dashboard that surfaces both, giving account managers and project managers a single view of the full customer lifecycle from initial lead through project completion. The dashboard has two main sections: an opportunities pipeline view showing active deals organized by stage (similar to a Kanban CRM), and a projects panel showing active project delivery with completion status. The key feature that makes this more than two separate views is linking them: when an opportunity is won and converted to a project, the dashboard should connect them visually — showing the transition from 'Closed Won' to 'In Progress Project.' Fetch opportunities with OPPORTUNITY_STATE=OPEN for the pipeline view. For projects, fetch with STATUS=IN_PROGRESS. To connect the two, use Insightly's CONVERTED_TO_PROJECT field on opportunities (a boolean indicating conversion) and the LINKS array that contains references to related objects. For the opportunity pipeline, group by PIPELINE_ID and then by STAGE_ID within each pipeline. Display stages in order using the stage order from GET /v3.1/Opportunities/Pipelines. Each opportunity card shows the amount (BID_AMOUNT), expected close date (CLOSE_DATE), and the linked organization name (ORGANISATION_NAME). For the projects panel, show a progress indicator based on completed vs total tasks. Fetch project tasks via GET /v3.1/Projects/{PROJECT_ID}/Tasks and count completed vs incomplete to calculate a percentage. Display a simple progress bar and a list of upcoming due tasks.

1// app/api/insightly/dashboard/route.ts
2import { NextResponse } from 'next/server';
3import { getOpportunities, getProjects } from '@/lib/insightly';
4
5export async function GET() {
6  try {
7    const [opportunities, projects] = await Promise.all([
8      getOpportunities('OPEN'),
9      getProjects('IN_PROGRESS'),
10    ]);
11
12    const totalOpportunityValue = (opportunities ?? []).reduce(
13      (sum, opp) => sum + (opp.BID_AMOUNT ?? 0),
14      0
15    );
16
17    return NextResponse.json({
18      opportunities: opportunities ?? [],
19      projects: projects ?? [],
20      summary: {
21        totalOpportunityValue,
22        openOpportunities: opportunities?.length ?? 0,
23        activeProjects: projects?.length ?? 0,
24      },
25    });
26  } catch (error) {
27    const message = error instanceof Error ? error.message : 'Unknown error';
28    return NextResponse.json({ error: message }, { status: 500 });
29  }
30}

Insightly's activity and notes system is key to using it as a full CRM — recording calls, meetings, and emails on contacts and opportunities provides context for the sales team and creates an audit trail of customer interactions. Insightly has two types of activity records: Notes (text-based comments attached to contacts, opportunities, or projects) and Tasks (actionable items with due dates and assigned users). Both use the same LINKS array mechanism to attach them to parent records. Create notes via POST /v3.1/Notes with a TITLE, NOTE_TEXT, and a LINKS array connecting the note to its parent object. For example, to add a note to an opportunity: { 'TITLE': 'Call with client', 'NOTE_TEXT': 'Discussed requirements...', 'LINKS': [{ 'LINK_OBJECT_NAME': 'Opportunity', 'LINK_OBJECT_ID': 12345 }] }. Create tasks via POST /v3.1/Tasks with TITLE, DUE_DATE, COMPLETED (boolean), RESPONSIBLE_USER_ID, and a LINKS array. Tasks appear in the Insightly UI as action items and can trigger notification emails to the assigned user when created via API. For the Bolt.new integration, add a form that allows team members to log notes against Insightly opportunities from the dashboard — a textarea that submits to a /api/insightly/notes route. This avoids the need to open Insightly just to log a quick call note, keeping team members in your custom interface while still maintaining Insightly as the system of record.

1// app/api/insightly/notes/route.ts
2import { NextResponse } from 'next/server';
3
4export async function POST(request: Request) {
5  const { title, text, opportunityId, contactId } = await request.json();
6
7  const apiKey = process.env.INSIGHTLY_API_KEY;
8  const base = process.env.INSIGHTLY_BASE_URL ?? 'https://api.insightly.com/v3.1';
9
10  if (!apiKey) {
11    return NextResponse.json({ error: 'INSIGHTLY_API_KEY not configured' }, { status: 500 });
12  }
13
14  const links: Array<{ LINK_OBJECT_NAME: string; LINK_OBJECT_ID: number }> = [];
15  if (opportunityId) links.push({ LINK_OBJECT_NAME: 'Opportunity', LINK_OBJECT_ID: opportunityId });
16  if (contactId) links.push({ LINK_OBJECT_NAME: 'Contact', LINK_OBJECT_ID: contactId });
17
18  const res = await fetch(`${base}/Notes`, {
19    method: 'POST',
20    headers: {
21      Authorization: `Basic ${Buffer.from(`${apiKey}:`).toString('base64')}`,
22      'Content-Type': 'application/json',
23    },
24    body: JSON.stringify({
25      TITLE: title,
26      NOTE_TEXT: text,
27      LINKS: links,
28    }),
29  });
30
31  if (!res.ok) {
32    return NextResponse.json({ error: 'Failed to create note' }, { status: res.status });
33  }
34
35  const note = await res.json();
36  return NextResponse.json({ noteId: note.NOTE_ID, title: note.TITLE });
37}