You can find our complete API documentation at
https://api.insightly.com/v3.1/Help#!
(documentation for v3.0 can be found here)
The Insightly web API enables developers to create custom applications and system integrations with Insightly CRM. You can use the API to do things like:
- Sync contacts and organizations across systems.
- Automate workflows, such as creating tasks to schedule follow up calls.
- Import or export information between other systems and Insightly.
The web API is a RESTful API that lets you fetch, create, update, and delete many types of Insightly objects, including leads, contacts, organizations, opportunities, projects, and events.
The API provides JSON encoded object graphs in response to requests. You can find detailed technical documents at https://api.insightly.com/v3.1/Help#! but here are a few notes to get you started.
Authentication
The Insightly API expects an Authorization header in HTTPS requests to determine which user is making calls to the API. You will need an API key for each user to uniquely identify them.
We use basic authentication, so you'll place the following in this header:
| Header | Value |
| Authorization | Basic nnnn |
Users can find the API key in their User Settings in the web application. You will need to Base64 encode the API key for the nnnn value.
Incorrect authentication will result in a 401 error. If you see the error, this is most likely because you are not using a valid API key or have not Base64 encoded it in the request header.
Limit Headers
In every API call response, the Insightly API will return two headers with the number of calls left in your 24 hour period.
X-RateLimit-Limit returns the currently set rate limit per day (based on your plan/subscription).
X-RateLimit-Remaining returns the number of requests left before the limit is reached.
XML
The Insightly API returns JSON by default. However, if you need XML output, you can include the header Content-Type: text/xml in your requests.
Working With Insightly Objects
To take a look at how Insightly works with objects, you can make GET requests to fetch fully populated objects such as contacts and organizations.
This will give you a good idea of what elements can be attached to an object. (You will need to consult the API documentation for details about required fields, expected error messages, etc.)
Note: A new API endpoint has been introduced to facilitate the display of a custom record on a user's screen in response to an incoming phone call. When a call is received by a CTI (Computer Telephony Integration) system, it associates the call with the newly created custom record. Both standard and custom objects will open in a new browser tab through the API.
Tip
IF YOU ARE USING A VERSION PRIOR TO 3.0 or 3.1:
When you update an object, you need to PUT (update) the entire object graph, including all sub-elements attached to the parent object (such as addresses and other contact points).
If you do not include these, or if you include invalid data in these elements, Insightly will interpret this as a request to remove these sub-elements from the parent item. This is a common source of misunderstanding and data loss, so be extra careful about this.
If you are using API V.30, note that when making a GET request from a standard object, it will not include link data.
You will need to make two requests: the first to pull the record data and the second to use the specific LINK endpoint based on the record ID from the record you pulled in the first request.
However, related data in custom objects will appear in the standard GET request. If you want to pull link data for a custom object, you only need to make one call. Related data will only appear if you have a lookup relationship looking up the custom object.
Sync Applications
To sync with external systems, you'll need to know which Insightly objects have been recently created or updated.
Most Insightly objects, including contacts, organizations, opportunities and projects, have a field named DATE_UPDATED_UTC which is the date/time (in Universal Coordinated Time) when the record was last updated.
You can compare this against a similar field in the external system to detect items that have been updated on one system or the other, and copy data across accordingly.