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