Working with the Insightly Web API

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.0/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.

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.)

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.

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.