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 to new leads and contacts.
  • Import or export information between other systems and Insightly.

The web API is a RESTful API that provides you with the ability to 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.insight.ly/v2.2/Help#!/. While the API is both comprehensive and straightforward to work with, there are a few things to be aware of that will help ease the learning curve.

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 

Where nnnn is the Base64 encoded output for your API key, which you can find by going to User Settings in the web application.

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. You can find your API key by going to User Settings, as shown below. User Settings API key

Client Side Libraries

If you are using .Net, Java, PHP, Python, or Ruby, you may also want to use our client-side wrapper libraries. These automate most aspects of interacting with the API and make it even easier to work with. You can find the libraries at github.com/insightly.

 

XML

The Insightly API returns JSON by default, as it is a more compact and easy-to-parse format. However, if you need XML output, you can include the header Content-Type: text/xml in your requests to specifically request XML in place of JSON.

Working With Insightly Objects

To get a sense of how Insightly works with objects, a good place to start is by making 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. (Of course, you should also 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

Syncing with external systems is a common API use case. To do this effectively, 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.

Full API Documentation

You can find complete API documentation at: https://api.insight.ly/v2.2/Help#!/. The documentation describes the expected parameters and behavior for all public API endpoints. As mentioned previously, the best way to probe the behavior of the API is to use the GET methods to request Insightly object graphs that were created via the web interface. This way you can see what typical objects look like, expected field values, and so on.

Have more questions? Submit a request
Top