How to Integrate Lovable with Insightly

Insightly uses API key authentication. Your personal API key is found in your Insightly account User Settings. To get your API key: log in to Insightly and click your profile avatar in the top-right corner. Select 'User Settings' from the dropdown. In User Settings, scroll to the 'API Key' section. Your API key is displayed — click the eye icon to show it and copy the full key string. The Insightly API base URL depends on which Insightly environment your account is on. Most Insightly accounts use: https://api.na1.insightly.com/v3.1/ (North America). However, Insightly has multiple regional endpoints: - North America: https://api.na1.insightly.com/v3.1/ - Europe/Australia: check your Insightly URL — if it ends in .co.uk or .com.au, use the eu1 endpoint To verify your endpoint: your Insightly account URL in the browser shows the region. For most US-based accounts, the API URL is https://api.na1.insightly.com/v3.1/. Insightly API authentication: HTTP Basic Auth with the API key as the username and an empty string as the password. In Base64: btoa(apiKey + ':'). The colon separates username from password in Basic Auth — with an empty password, the colon must still be present. Insightly also provides a unique API URL per user visible at the bottom of the User Settings page under 'API URL' — this shows your exact regional API base URL. Use this value directly.

Add Insightly credentials to Lovable's Cloud Secrets panel. In Lovable, click '+' → Cloud panel → Secrets. Add two secrets: - INSIGHTLY_API_KEY — your personal API key from Insightly User Settings - INSIGHTLY_API_URL — the full API base URL from Insightly User Settings (e.g., https://api.na1.insightly.com/v3.1/) The Edge Function constructs API endpoints by appending resource paths to the base URL: contacts, organizations, opportunities, projects. The Authorization header is constructed as: btoa(INSIGHTLY_API_KEY + ':'). Note the colon after the key — this is the HTTP Basic Auth separator between username (API key) and password (empty string). Insightly API v3.1 supports standard REST methods. List endpoints accept skip and top query parameters for pagination (Insightly uses top for page size and skip for offset). The default page size is 100 records — use $top and $skip for pagination: GET /contacts?$top=25&$skip=50 — returns records 51-75. Insightly also uses OData-style filter syntax for searching: GET /contacts?brief=false&top=10&skip=0&convertDates=true returns structured date objects. For searching by email: GET /contacts/search?field_name=EMAIL_ADDRESS&field_value=user@example.com.

Build the Edge Function that handles Insightly operations. The function constructs the Basic Auth header and proxies requests to the correct Insightly API endpoint. Insightly API v3.1 endpoint patterns: - Contacts: GET /contacts, POST /contacts, GET /contacts/{id}, PUT /contacts/{id} - Organizations: GET /organisations, POST /organisations (note UK spelling) - Opportunities: GET /opportunities, POST /opportunities, PUT /opportunities/{id} - Projects: GET /projects, POST /projects, PUT /projects/{id} - Search contacts by email: GET /contacts/search?field_name=EMAIL_ADDRESS&field_value=user@example.com Insightly uses UK English in some endpoint names: 'organisations' (not 'organizations'). This is a common source of 404 errors. For creating linked records (opportunity linked to a contact and organization), Insightly uses a 'LINKS' array in the request body. Each link specifies the linked record type and ID: { LINK_SUBJECT_TYPE: 'CONTACT', LINK_SUBJECT_ID: contactId, ROLE: 'Responsible' }. Opportunity OPPORTUNITY_STATE field values: 'OPEN', 'WON', 'ABANDONED', 'LOST', 'SUSPENDED'. Project STATUS field values: 'NOT_STARTED', 'IN_PROGRESS', 'COMPLETED', 'OVERDUE', 'ABANDONED'. Insightly returns dates in ISO 8601 format and uses nullable fields liberally — handle null values in your React components to avoid undefined rendering errors.

1import { serve } from 'https://deno.land/std@0.168.0/http/server.ts'
2
3const corsHeaders = {
4  'Access-Control-Allow-Origin': '*',
5  'Access-Control-Allow-Headers': 'authorization, x-client-info, apikey, content-type',
6}
7
8function insightlyHeaders() {
9  const key = Deno.env.get('INSIGHTLY_API_KEY')
10  if (!key) throw new Error('INSIGHTLY_API_KEY not configured')
11  return {
12    Authorization: `Basic ${btoa(key + ':')}`,
13    'Content-Type': 'application/json',
14    Accept: 'application/json',
15  }
16}
17
18function insightlyUrl(path: string) {
19  const base = Deno.env.get('INSIGHTLY_API_URL')!
20  return `${base}${path}`
21}
22
23serve(async (req) => {
24  if (req.method === 'OPTIONS') return new Response('ok', { headers: corsHeaders })
25
26  try {
27    const { action, params = {} } = await req.json()
28    const headers = insightlyHeaders()
29    let resp: Response
30
31    switch (action) {
32      case 'list_contacts':
33        resp = await fetch(insightlyUrl(`contacts?top=${params.top || 25}&skip=${params.skip || 0}`), { headers })
34        break
35
36      case 'search_contact':
37        resp = await fetch(insightlyUrl(`contacts/search?field_name=EMAIL_ADDRESS&field_value=${encodeURIComponent(params.email)}`), { headers })
38        break
39
40      case 'create_contact':
41        resp = await fetch(insightlyUrl('contacts'), {
42          method: 'POST',
43          headers,
44          body: JSON.stringify({
45            FIRST_NAME: params.firstName,
46            LAST_NAME: params.lastName,
47            EMAIL_ADDRESS: params.email,
48            PHONE: params.phone || '',
49            ORGANISATION_ID: params.organisationId,
50          }),
51        })
52        break
53
54      case 'list_opportunities':
55        resp = await fetch(insightlyUrl(`opportunities?top=${params.top || 25}&skip=${params.skip || 0}`), { headers })
56        break
57
58      case 'create_opportunity':
59        resp = await fetch(insightlyUrl('opportunities'), {
60          method: 'POST',
61          headers,
62          body: JSON.stringify({
63            OPPORTUNITY_NAME: params.name,
64            OPPORTUNITY_STATE: 'OPEN',
65            BID_AMOUNT: params.amount,
66            BID_CURRENCY: params.currency || 'USD',
67            CLOSE_DATE: params.closeDate,
68            RESPONSIBLE_USER_ID: params.responsibleUserId,
69            LINKS: params.links || [],
70          }),
71        })
72        break
73
74      case 'update_opportunity_state':
75        resp = await fetch(insightlyUrl(`opportunities/${params.opportunityId}`), {
76          method: 'PUT',
77          headers,
78          body: JSON.stringify({ OPPORTUNITY_STATE: params.state }),
79        })
80        break
81
82      case 'list_projects':
83        resp = await fetch(insightlyUrl(`projects?top=${params.top || 25}&skip=${params.skip || 0}`), { headers })
84        break
85
86      case 'create_project':
87        resp = await fetch(insightlyUrl('projects'), {
88          method: 'POST',
89          headers,
90          body: JSON.stringify({
91            PROJECT_NAME: params.name,
92            STATUS: 'IN_PROGRESS',
93            RESPONSIBLE_USER_ID: params.responsibleUserId,
94            START_DATE: params.startDate || new Date().toISOString().split('T')[0],
95            END_DATE: params.endDate,
96            LINKS: params.links || [],
97          }),
98        })
99        break
100
101      default:
102        return new Response(JSON.stringify({ error: 'Unknown action' }), {
103          status: 400, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
104        })
105    }
106
107    const data = await resp.json()
108    return new Response(JSON.stringify(data), {
109      status: resp.ok ? 200 : resp.status,
110      headers: { ...corsHeaders, 'Content-Type': 'application/json' },
111    })
112  } catch (error) {
113    return new Response(JSON.stringify({ error: error.message }), {
114      status: 500, headers: { ...corsHeaders, 'Content-Type': 'application/json' },
115    })
116  }
117})

With the Edge Function deployed, use Lovable's chat to build the dashboard that makes Insightly's linked opportunity-to-project model visible. This is the unique value of Insightly — a single view showing both pipeline status and delivery progress. For the combined sales and projects view, fetch opportunities in parallel with projects and display them in a tabbed or split layout. On the 'Pipeline' tab, show open opportunities sorted by close date. On the 'Projects' tab, show active projects with percent complete and status. Use the LINKS array on each record to surface connections between them. For creating the opportunity-to-project transition workflow, build an 'Mark as Won' button on opportunity detail views. Clicking it calls update_opportunity_state with state 'WON', then immediately calls create_project with the opportunity name, linked contact, and linked organization (passed in the LINKS array). Show a success state with the new project ID and a link to the project detail view. For client-facing portals, filter projects by the client's organization ID. Insightly project records include LINKS to their associated organizations — query projects and filter by ORGANISATION_ID in the links array to show only the client's projects. For teams using Insightly with detailed task tracking, add a task completion view for each project using the /tasks endpoint filtered by project ID. RapidDev's team can help design complex multi-record dashboards that efficiently batch Insightly API calls for large client lists.