# How to Integrate Retool with Insightly

- Tool: Retool
- Difficulty: Beginner
- Time required: 20 minutes
- Last updated: April 2026

## TL;DR

Connect Retool to Insightly using a REST API Resource with Basic Auth — use your Insightly API key as the username and leave the password blank. Build a CRM and project management dashboard that manages contacts, organizations, opportunities, and projects from Insightly's API base URL (https://api.insightly.com/v3.1/), combining Insightly's unique CRM-plus-project-management data model in one Retool interface.

## Build an Insightly CRM and Project Management Dashboard in Retool

Insightly's core differentiation from other CRMs is its built-in project management layer: when an opportunity is won, Insightly can automatically create a project from it, carrying over contact links, tasks, and milestones. This makes Insightly particularly valuable for service businesses where sales and delivery are tightly coupled — consultancies, agencies, professional services firms. Building a Retool dashboard on top of Insightly lets teams manage both the pipeline and the delivery side from a unified interface faster than Insightly's native UI.

With a Retool-Insightly integration, you can build a contact and organization management panel that shows contact relationship history, linked opportunities, and associated projects in one view. You can create a project operations dashboard that tracks active project health, milestone completion rates, and task assignments across all ongoing client engagements. Or you can build a pipeline analytics view that combines opportunity data with project delivery metrics to give leadership a complete revenue-to-delivery picture.

Insightly's API key Basic Auth pattern is one of the simplest authentication setups for any CRM — no OAuth flows, no token exchange, just a Base64-encoded API key that works immediately. This makes the initial Retool configuration quick and the resulting integration reliable for long-lived dashboards used by operations teams.

## Before you start

- An Insightly account with API access (available on Plus, Professional, and Enterprise plans)
- Your Insightly API key, found in User Settings → API Key section of your Insightly account
- A Retool account with permission to create Resources
- Basic understanding of REST API concepts and how Basic Auth works
- Familiarity with Insightly's data model (contacts, organizations, opportunities, projects, pipelines)

## Step-by-step guide

### 1. Locate your Insightly API key

Insightly uses a simple API key for authentication — finding and copying it is the only setup required on the Insightly side. Log in to your Insightly account and click your user avatar or name in the top-right corner of the navigation. Select 'User Settings' from the dropdown menu. In the User Settings page, scroll down to find the 'API Key' section. Your API key is displayed as a string — it looks similar to a GUID format. If no key is shown, click 'Generate API Key' to create one. Click the copy icon next to the key to copy it to your clipboard. Keep this key secure — it provides full API access to your Insightly account without any additional authentication. Note that the Insightly API uses this key in a specific way: it is sent as a Basic Auth credential where the key is the username and the password is empty. Retool's Basic Auth configuration in the resource settings handles this format — you enter the API key in the username field and leave the password field blank. After copying the key, store it in a secure location (password manager or secrets manager) before proceeding to Retool configuration.

**Expected result:** You have your Insightly API key copied and ready to paste into Retool's resource configuration.

### 2. Create the Insightly REST API Resource in Retool

In Retool, click the Resources tab in the left sidebar and click Add Resource. Select REST API from the resource type list. Name the resource 'Insightly CRM'. In the Base URL field, enter: https://api.insightly.com/v3.1 — this is the current Insightly API version. Do not include a trailing slash. Scroll to the Authentication section and select Basic Auth from the dropdown. In the Username field, paste your Insightly API key that you copied in the previous step. Leave the Password field completely empty — Insightly's Basic Auth pattern uses the API key as the username with no password. Scroll to the Headers section and add a default header to ensure JSON responses: set the Accept key to application/json. Also add a Content-Type header set to application/json for POST and PUT request bodies. Click Save Changes. To verify the connection, you can test it immediately by creating a simple GET query after saving the resource. In a new Retool app, create a query against this resource with Method GET and Path /Users/me — this endpoint returns your Insightly user profile and is a quick way to confirm authentication is working correctly. If you see your user profile data in the Results panel, the resource is correctly configured.

**Expected result:** An Insightly CRM resource appears in your Resources list. A test query to /Users/me returns your Insightly user profile, confirming the API key and Basic Auth are correctly configured.

### 3. Query Insightly contacts, organizations, and opportunities

Create the core data queries for the CRM dashboard. In a Retool app, open the Code panel and click + to create a new query. Select your Insightly CRM resource. Name the first query 'getContacts'. Set Method to GET and Path to /Contacts. Add URL parameters: 'top' set to {{ 50 }} (controls result count), 'skip' set to {{ (pagination.page - 1) * 50 || 0 }} for pagination, and 'search' set to {{ searchInput.value }} for filtering by name or email (leave unbound for the initial query). The Insightly API returns contacts with custom fields as an array of { FIELD_NAME, FIELD_VALUE } objects — you will need a transformer to flatten these. Create a second query named 'getOrganizations' with Method GET, Path /Organisations (note: UK spelling in Insightly's API). Add similar pagination parameters. Create a third query named 'getOpportunities' with Method GET and Path /Opportunities. Add a parameter 'opportunity_state' to filter by 'Open', 'Won', or 'Abandoned'. Set all three queries to run when the app loads. Add JavaScript transformers to normalize the custom fields array in contact and organization records into named properties for easy column configuration in Retool Tables.

```
// Transformer: normalize Insightly contact with custom fields
const contacts = Array.isArray(data) ? data : [];
return contacts.map(contact => {
  // Flatten custom fields array into named properties
  const customFields = {};
  (contact.CUSTOMFIELDS || []).forEach(cf => {
    customFields[cf.FIELD_NAME] = cf.FIELD_VALUE;
  });
  
  return {
    id: contact.CONTACT_ID,
    name: [contact.FIRST_NAME, contact.LAST_NAME].filter(Boolean).join(' ') || '(No name)',
    email: contact.EMAIL_ADDRESS || '',
    phone: contact.PHONE || '',
    title: contact.TITLE || '',
    owner: contact.OWNER_USER_ID || '',
    date_created: contact.DATE_CREATED_UTC
      ? new Date(contact.DATE_CREATED_UTC).toLocaleDateString()
      : '',
    date_updated: contact.DATE_UPDATED_UTC
      ? new Date(contact.DATE_UPDATED_UTC).toLocaleDateString()
      : '',
    ...customFields
  };
});
```

**Expected result:** The getContacts, getOrganizations, and getOpportunities queries return normalized arrays of records ready for display in Retool Table components.

### 4. Build the CRM dashboard with project management view

Assemble the dashboard interface using a Tabs component to organize the different Insightly data types. Create tabs for Contacts, Organizations, Opportunities, and Projects. In the Contacts tab, drag a Text Input component for search (name it 'searchInput') and a Table component. Set the Table's Data to {{ getContacts.data }}. Configure columns: name, email, phone, title, date_created. Add a row click event handler that triggers a query 'getContactDetail' (GET /Contacts/{{ contactsTable.selectedRow.id }}) and displays the full contact in a detail Container with sections for linked organizations, tags, and notes. In the Opportunities tab, drag a Table bound to {{ getOpportunities.data }} with columns for opportunity name, bid_amount, bid_currency, close_date, and stage. In the Projects tab, create a query named 'getProjects' (GET /Projects with 'project_state' parameter). Add a Chart component showing project count by pipeline stage above the projects Table. To create a new contact from Retool, add a 'New Contact' button that opens a Modal containing a Form. Create a 'createContact' query with Method POST, Path /Contacts, Body Type JSON, and a body mapping form field values to Insightly contact property names. Set the On Success handler to trigger getContacts to refresh and show a success notification.

```
// Query body: create new Insightly contact
// Method: POST  Path: /Contacts
{
  "FIRST_NAME": {{ JSON.stringify(firstNameInput.value) }},
  "LAST_NAME": {{ JSON.stringify(lastNameInput.value) }},
  "EMAIL_ADDRESS": {{ JSON.stringify(emailInput.value) }},
  "PHONE": {{ JSON.stringify(phoneInput.value) }},
  "TITLE": {{ JSON.stringify(titleInput.value) }},
  "CUSTOMFIELDS": []
}
```

**Expected result:** A tabbed Retool dashboard displays Contacts, Organizations, Opportunities, and Projects from Insightly, each with a searchable Table and a detail view for the selected record.

### 5. Add opportunity-to-project bridging and pipeline analytics

Build the unique CRM-to-project-management bridge that makes Insightly valuable for service businesses. Create a query named 'getLinkedProjects' that retrieves projects associated with a selected opportunity: Method GET, Path /Opportunities/{{ opportunitiesTable.selectedRow.OPPORTUNITY_ID }}/Links. The Links endpoint returns all linked records (contacts, organizations, projects) for a given opportunity. Filter the response in a transformer to show only items where LINK_OBJECT_NAME equals 'Project', then cross-reference with the getProjects query data to display project names and statuses. To build a pipeline analytics view, create a JavaScript query named 'calculatePipelineStats' that processes the raw opportunities data from getOpportunities to compute metrics: total open pipeline value (sum of BID_AMOUNT for open opportunities), weighted pipeline value (BID_AMOUNT * probability / 100), average deal size, and win rate. Display these as Statistic components at the top of the dashboard. Add a Chart component showing opportunities by pipeline stage using a Bar chart. Create a second Chart showing monthly opportunity creation count using a Line chart. For teams that want to link Insightly project health to CRM opportunity data in complex ways — combining project task completion with opportunity value to calculate delivery risk — RapidDev's team can help architect and build your Retool operations dashboard.

```
// JavaScript query: calculate pipeline summary statistics
const opportunities = getOpportunities.data || [];
const openOpps = opportunities.filter(o => o.opportunity_state === 'Open');

const totalPipeline = openOpps.reduce((sum, o) => sum + (o.BID_AMOUNT || 0), 0);
const weightedPipeline = openOpps.reduce(
  (sum, o) => sum + ((o.BID_AMOUNT || 0) * (o.PROBABILITY || 0) / 100), 0
);
const wonOpps = opportunities.filter(o => o.opportunity_state === 'Won');
const winRate = opportunities.length > 0
  ? (wonOpps.length / opportunities.length * 100).toFixed(1)
  : 0;

return {
  total_pipeline: '$' + totalPipeline.toLocaleString(),
  weighted_pipeline: '$' + Math.round(weightedPipeline).toLocaleString(),
  win_rate: winRate + '%',
  open_count: openOpps.length,
  avg_deal_size: openOpps.length > 0
    ? '$' + Math.round(totalPipeline / openOpps.length).toLocaleString()
    : '$0'
};
```

**Expected result:** The dashboard displays pipeline analytics statistics and Charts for opportunity data, and a selected opportunity shows its linked projects via the Insightly Links API.

## Best practices

- Store your Insightly API key in Retool Configuration Variables as a secret (Settings → Configuration Variables) rather than directly in the resource username field — this enables key rotation without reconfiguring the resource
- Use Insightly's Links API (/Contacts/{id}/Links, /Opportunities/{id}/Links) to navigate relationships between CRM objects rather than building separate queries for each relationship — this reduces the number of API calls needed to build rich detail views
- Apply transformers to flatten Insightly's custom fields array (CUSTOMFIELDS) into named properties immediately after retrieval — this makes column configuration in Retool Tables much simpler and avoids repetitive array-search code throughout the app
- Limit GET requests to the fields you actually display using Insightly's field filtering parameters to reduce response payload size for large contact or organization databases
- Add pagination controls using Insightly's 'top' and 'skip' parameters for any Table that may contain more than 100 records — loading all records without pagination is slow and may cause browser memory issues for large accounts
- Use Insightly's bulk APIs (where available) for batch operations rather than looping individual API calls — for large-scale tag assignments or field updates, Retool Workflows with Loop blocks and batch API calls are more reliable
- Implement confirmation dialogs before any delete or bulk update operations to prevent accidental data loss in the production Insightly account

## Use cases

### Build a contact and organization CRM panel with relationship linking

Create a Retool panel that displays Insightly contacts and organizations in a searchable Table, with a detail panel showing each contact's linked organizations, opportunities, and projects. Add a relationship visualization using Charts showing contact activity over time. Include quick-action buttons for creating follow-up tasks, adding notes, and linking contacts to existing opportunities — giving sales teams a faster CRM interface than Insightly's native form-heavy UI.

Prompt example:

```
Build a Retool CRM dashboard that searches Insightly contacts by name or email and displays results in a Table with columns for name, email, organization, owner, and date created. When a contact is selected, show a detail panel with their linked organizations, open opportunities, associated projects, and recent activity notes. Add a button to create a new task linked to the selected contact.
```

### Build a project operations and milestone tracking dashboard

Create a Retool project management panel that lists all active Insightly projects with their pipeline stage, responsible user, and completion percentage. Show milestone status, overdue tasks, and team workload distribution in Charts. Add a task assignment panel where project managers can assign tasks to team members and update task status directly from Retool. This gives delivery teams a faster, more customizable project view than Insightly's built-in project boards.

Prompt example:

```
Build a Retool project dashboard that queries all active Insightly projects and displays them in a Table grouped by pipeline stage with columns for project name, responsible user, start date, expected close date, and percentage complete. Add a detail panel showing tasks and milestones for the selected project, with task status update buttons and overdue task highlighting.
```

### Build a sales-to-delivery pipeline bridging opportunities and projects

Create a Retool analytics dashboard that shows the full Insightly business pipeline from opportunity stage through project delivery. Display opportunities in the closing stage alongside newly created projects, tracking the conversion from won deals to active delivery. Show revenue pipeline value in Charts alongside project delivery capacity to help leadership balance sales commitments with delivery resources. Add pipeline stage transition tracking to identify bottlenecks in the sales-to-delivery handoff.

Prompt example:

```
Build a Retool business intelligence panel that queries both Insightly opportunities (filtered to closing stage and recently won) and associated projects. Display a Chart showing opportunity value by stage alongside a Table of projects created from won opportunities. Include a revenue pipeline Chart and a project delivery capacity Chart to compare incoming sales commitments with current project load.
```

## Troubleshooting

### 401 Unauthorized error when testing the Insightly resource connection

Cause: The Insightly API expects the API key as the Basic Auth username with an empty password. If the password field contains any value, or if the API key is entered in the wrong field, authentication fails with a 401 error.

Solution: In Retool's Insightly Resource settings, verify the API key is in the Username field. Confirm the Password field is completely empty — even a space character in the password field will cause authentication failure. Re-copy the API key from Insightly's User Settings to ensure no characters were truncated. If the error persists, regenerate a new API key in Insightly and update the resource.

### Contact or organization queries return empty arrays despite records existing in Insightly

Cause: Insightly's search parameter is case-sensitive for certain fields, and some filter parameters require specific format. Additionally, the 'search' parameter may require at least 2 characters to return results.

Solution: Remove all filter parameters temporarily and run the base GET /Contacts query to verify data returns. If the base query succeeds, add filters back one at a time to identify which parameter is causing the empty result. Verify search inputs have at least 2 characters before triggering the query by adding a conditional: only run the query when searchInput.value.length >= 2 OR searchInput.value === ''.

### Custom field values are missing or showing as null in the Retool Table after the transformer runs

Cause: Insightly returns custom fields as an array of objects with FIELD_NAME and FIELD_VALUE properties. If the transformer is looking for direct property access (contact.MY_CUSTOM_FIELD) rather than iterating the CUSTOMFIELDS array, custom field values are not found.

Solution: Ensure your transformer iterates the CUSTOMFIELDS array and builds a flat object: (contact.CUSTOMFIELDS || []).forEach(cf => { customFields[cf.FIELD_NAME] = cf.FIELD_VALUE; }). Check the raw API response in the Retool query Results panel to confirm the exact FIELD_NAME values used in your Insightly account — custom field names are case-sensitive and must match exactly.

### POST requests to create contacts or opportunities return 400 Bad Request errors

Cause: Insightly's API requires specific property name formats (ALL_CAPS_WITH_UNDERSCORES) and may require certain mandatory fields. Using lowercase or camelCase property names, or omitting required fields, causes 400 validation errors.

Solution: Check the Insightly API documentation for the exact required fields for the contact or opportunity create endpoint. FIRST_NAME and LAST_NAME are required for contacts; OPPORTUNITY_NAME and RESPONSIBLE_USER_ID are required for opportunities. Verify all property names in your POST body use the ALL_CAPS format. Review the error response body in Retool's query Results panel — it typically includes a descriptive message about which field failed validation.

## Frequently asked questions

### Does Retool have a native Insightly connector?

No, Retool does not have a native Insightly connector. You connect using a REST API Resource with Basic Auth, where the Insightly API key is the username and the password is left empty. The Insightly API base URL is https://api.insightly.com/v3.1/. This setup takes about 5 minutes and works reliably without OAuth complexity.

### How does Insightly's API handle relationships between contacts, organizations, and projects?

Insightly uses a Links API to represent relationships between objects. Every major entity (Contact, Organization, Opportunity, Project) has a /Links sub-endpoint that returns associated records of any type. For example, GET /Opportunities/{id}/Links returns all contacts, organizations, and projects linked to that opportunity. Use these link endpoints in Retool to build detail views that show relationship context without requiring separate lookup queries for each related entity type.

### What is the Insightly API rate limit?

Insightly's API rate limits depend on your plan. The Plus plan allows 50,000 API requests per day, the Professional plan allows 100,000 per day, and Enterprise plans offer higher limits. If you hit rate limits, Retool queries will receive 429 Too Many Requests responses. Add query caching (30-60 seconds) to frequently-accessed list queries to reduce API call volume when multiple users access the dashboard simultaneously.

### Can I use Retool to manage Insightly projects and tasks?

Yes. The Insightly API includes full CRUD endpoints for Projects (/Projects), Tasks (/Tasks), Milestones (/ProjectMilestones), and Events (/Events). You can build a project task board in Retool that creates tasks, updates their status and assignee, marks milestones complete, and tracks project pipeline stage. Use GET /Projects with the 'project_state' parameter to filter active vs completed projects.

---

Source: https://www.rapidevelopers.com/retool-integrations/insightly
© RapidDev — https://www.rapidevelopers.com/retool-integrations/insightly