Tuesday, 21 August 2012

Introducing the Insightly REST API

Insightly API Documentation

For users on our paid plans, today we're introducing our REST based web Application Programmer Interface (API) that allows you to automate data retrieval and modification in Insightly. We support JSON and XML based requests, and most of the data stored in Insightly can be accessed and updated via the API.

For full documentation on our API, please visit our developer website at: 

As far as HTTP REST API's go, ours is pretty conventional and you should be able to pick it up pretty quickly if you've used one before. We support four HTTP verbs - GET requests to retrieve information, POST to add new records, PUT to update records, and DELETE requests to remove records. To get an indication of the fields returned for any record type, the easiest way is just to perform a GET request of the top level items to get a list of objects back (see below).

Authentication and Permissions

Insightly uses HTTP Basic authentication in order to determine which user is making calls to the API. You'll need an API key for each user to uniquely identify them making calls to the API, and this can be found by logging into Insightly and going to the 'My Info' page, then the User Settings tab. The 'My Info' page can be accessed via the small card icon in the top right corner.

You'll need to include your API key as the user name (Base64 encoded), and you can leave the password blank or put in whatever password you like - Insightly will ignore it. All the calls you make to the API will be as this user, and permissions to view, edit and delete records via the API will be the same as those available to that user through the Insightly website.

HTTP Compression

The Insightly API requires all calls be made via HTTPS, and we support both GZIP and DEFLATE compression to reduce the payload size of data sent back to the client. Just add an 'Accept-Encoding' header to your calls to indicate your support for returning compressed responses.

Supported Content Types

If no content-type header is included in your call, we return JSON data by default. If you include a header of "content-type: text/xml" we will accept and return an XML representation of the data.

Example API Call

If we wanted to retrieve all the contacts available to a particular user with an API key of
and we wanted a JSON response that's GZIP encoded, we would use the following GET call with both the Authorization header and Accept-Encoding header:

GET: https://api.insight.ly/v2/contacts
Authorization: Basic YWM5YTIyOTItZjI1YS00NDgzLTlkNTQtMDAwMDAwMDAwMDAw
Accept-Encoding: gzip

Limiting Returned Records

If a request is to return over 10,000 records, only the parent objects will be returned in the result and any child objects (eg: addresses, phone numbers, links etc) will be omitted to reduce response sizes. This is mostly applicable to large contact lists, organization lists, or task lists. To retrieve the child objects, request each individual record from the server by ID, or use a querystring of $top to limit records returned (see below).

For requests returning less than 10k records, you can force the API to return just the top level records without child objects by including the "Brief" query string parameter as shown below. This is supported by GET requests to /Contacts, /Organizations, /Opportunities, /Projects, /Tasks, /Emails and /Notes

The Insightly API supports two query string parameters on GET request to give you some flexibility around  the data returned. To specify a specific number of records to be returned, add a $top query parameter with the number of records. For example to return just the top 20 contact records, you would use a GET request of: https://api.insight.ly/v1/contacts?$top=20

To skip the first 50 records and return the next 20 after that (useful for paging records) we can use a combination of the TOP and SKIP query parameters as follows:

For full documentation on our API, please visit our developer website at: 

If you have any feedback or questions about the API, please send an email to support@insight.ly and we'll put you in touch with one of our developers. Thanks.