Submit a request

How can we help?

Articles in this section

See more

Insightly Web API

Updated

The Web API lets developers build custom applications and integrations against Insightly. This covers access management, finding your credentials, troubleshooting, and the Zapier connection.

On this page:

Documentation

Full API documentation is published at api.insightly.com, with separate references for the current version (v3.1) and the previous one (v3.0).

The web API is RESTful and JSON-encoded by default, letting you fetch, create, update, and delete objects like leads, contacts, organizations, opportunities, projects, and events. Typical uses: syncing contacts and organizations across systems, automating workflows such as creating follow-up tasks, and importing or exporting data between Insightly and another system. If you need XML instead of JSON, include a Content-Type: text/xml header on the request.

Authentication

Every request needs an Authorization header carrying a Base64-encoded API key, using basic authentication: Authorization: Basic <encoded key>. An incorrect or unencoded key returns a 401 error.

Rate limits

Every response includes two headers: X-RateLimit-Limit, the daily limit for your plan, and X-RateLimit-Remaining, how many requests are left before you hit it.

⚠️ On API versions before 3.0/3.1, a PUT request replaces the entire object graph, not just the fields you send. Omitting a sub-element, such as an address or other contact point, or sending invalid data in one, is interpreted as a request to remove it. This is a common source of accidental data loss on the older API versions.

On v3.0, a GET request against a standard object doesn’t include link data. Getting it takes two requests: the initial record fetch, then a separate call to that record’s LINK endpoint using its ID. Custom objects don’t have this limitation. Related data appears in the standard GET request already, and pulling link data for a custom object only takes one call, provided a lookup relationship on the custom object exists.

Detecting changes for sync

Most Insightly objects carry a DATE_UPDATED_UTC field, the UTC timestamp of the record’s last update. Comparing it against an equivalent field in the external system is how a sync integration detects which side has the more recent change.

Finding your API key and URL

Both are needed to configure most integrations. Find them from the user icon in the top right of the CRM navigation.

Accessing User Settings from Profile Menu — This shows the dropdown menu that appears when clicking your profile icon in the top-right corner of Insightly, with “User Settings” highlighted in blue. Navigating to User Settings from this menu is how users access and manage their personal account preferences and configuration options.

1 Accessing User Settings from Profile Menu

 Insightly User Settings Configuration Page — This screenshot shows the User Settings panel in Insightly CRM, displaying options for email, task, calendar, connected apps, and API settings. It would help users locate and adjust personal preferences such as Gmail integration, email visibility, reminder times, and their API key.

2 Insightly User Settings Configuration Page

ℹ️ If the API key field shows “API Access is disabled” instead of a key, that’s expected until API access is turned on for your account. The key only appears once access has been enabled; see Managing API access below.

Clicking Generate New API Key immediately revokes the old one, so any application still using it will stop working until you update it with the new key. Changing a user’s administration permissions also resets their API key automatically.

API Access Disabled Status Message — This screenshot shows the API section of Insightly CRM displaying the message “Your API key is: API Access is disabled,” indicating that API access has not been enabled for the user’s account. This would be relevant to someone troubleshooting why they cannot retrieve an API key or connect Insightly to third-party integrations.

Managing API access

By default, every user in your account has API access. Administrators can turn access on or off per user, which is worth reviewing before granting a developer credentials.

Accessing Edit User Options in User List — The image shows the User Details page in Insightly’s System Settings, with the Actions dropdown menu open and “Edit User” highlighted. This demonstrates how administrators can modify a user’s details, change their email address, or delete the user from the system.
Enabling API Access for an Insightly User — The screenshot shows the User Details page in Insightly’s System Settings, with the API Access checkbox checked and highlighted in red. This setting must be enabled for a user to authenticate and interact with the Insightly API.

Troubleshooting with Postman

When working with Insightly support on an API problem, sharing the exact request helps diagnose it. Use the Postman app to create, save, and share the request.

Postman Create New Request Dialog — The Postman application is open showing the “Create New” dialog with options for building blocks like Request, Collection, and Environment, as well as advanced options like API Documentation, Mock Server, and Monitor. This screen is the starting point for setting up API calls, which is relevant for integrating or testing connections with Insightly’s API.

1 Postman Create New Request Dialog

 Saving API Request to Insightly Collection in Postman — The image shows the “Save Request” dialog in Postman, where a request named “My API Request” is being saved to a collection called “Insightly.” This step is important for organizing and reusing API requests when integrating with Insightly’s API.

2 Saving API Request to Insightly Collection in Postman

 Selecting Basic Auth in Postman Authorization — The image shows a Postman API client with the Authorization type dropdown open, highlighting the “Basic Auth” option being selected for an Insightly API test request. This is relevant for users who need to authenticate API calls to Insightly using a username and password combination.

3 Selecting Basic Auth in Postman Authorization
Postman Basic Auth Send Request Setup — The image shows a Postman API request window configured with Basic Authentication, where Username and Password fields are visible along with a highlighted Send button. This is relevant for readers who need to authenticate API calls to Insightly CRM using basic credentials before sending a test request.

4 Postman Basic Auth Send Request Setup

 Postman Collection Context Menu Options — A Postman collection named “TRTest” has its three-dot menu open, revealing options including Share Collection, Rename, Edit, and Add Folder. This helps users understand how to manage their API collections when working with Insightly’s API through Postman.

5 Postman Collection Context Menu Options

 Postman Share Collection Get Link Tab — This shows the “Share Collection” dialog in Postman with the “Get Link” tab selected, which allows users to generate a shareable link for others to access their API collections. A user would click the orange “Get Link” button to create the link, which can then be managed from the Postman Dashboard.

6 Postman Share Collection Get Link Tab

Zapier

Zapier connects Insightly to hundreds of other apps without code, and Zapier maintains setup notes for the most popular Insightly zaps.

Related to

Related articles

Powered by Zendesk