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. We're going to include a dedicated developer site with more detailed information in the near future, but we're putting this preliminary documentation out now so those that would like to use the API can do so immediately.
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.
If we wanted to retrieve all the contacts available to a particular user with an API key of
ac9a2292-f25a-4483-9d54-000000000000
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/v1/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
https://api.insight.ly/v1/contacts?Brief=True
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:
https://api.insight.ly/v1/contacts?$skip=50&$top=20
API End Points Reference
All calls to the Insightly API will start with "https://api.insight.ly/v1/" for the first version of the API. We only support HTTPS requests, and all requests must use HTTP Basic authentication with a paid user API Key as the user name in each request. We support both JSON and XML requests and responses as governed by the Content-Type header, with JSON being the default if no header is present, and we support both Gzip and Deflate compression.
The ID of each individual record is an integer, and is used to reference individual records for retrieval, update and delete.
Quick Reference of all API Paths
/Contacts
/Contacts/:id
/Contacts/:id/image
/Contacts/:id/Notes - Get Only
/Contacts/:id/Emails - Get Only
/Organisations
/Organisations/:id
/Organisations/:id/image
/Organisations/:id/Notes - Get Only
/Organisations/:id/Emails - Get Only
/Tasks
/Tasks/:id
/TaskCategories
/TaskLinks - Get Only
/Tags/Contacts - Get Only
/Tags/Organisations - Get Only
/Tags/Opportunities - Get Only
/Tags/Projects - Get Only
/Tags/Emails - Get Only
/Opportunities
/Opportunities/:id
/Opportunities/:id/image
/Opportunities/:id/Notes - Get Only
/Opportunities/:id/Emails - Get Only
/OpportunityCategories
/OpportunityStateChange/:id - PUT only with new State Reason in body.
/OpportunityStateReasons - GET only - list of all reasons
/Projects
/Projects/:id
/Projects/:id/image
/Projects/:id/Notes - Get Only
/Projects/:id/Emails - Get Only
/ProjectCategories
/Emails
/Emails?Brief=True -- Does not get body extract or file attachments or note links
/Emails/:id -- Get and Delete Only
/Emails/:id/comments
/EmailLinks
/Events
/Events/:id
/Notes -- Gets Only first 100 characters of each Note Body
/Notes?Brief=True -- Does not get body or file attachments or note links
/Notes/:id -- Includes full note body
/Notes/:id/comments
/NoteLinks - Get Only
/Comments/:id -- Get, Put, Delete Only
/FileAttachments/:id - Get Only
/FileCategories
/Teams
/Teams/:id
/TeamMembers
/TeamMembers/:id
/Pipelines
/Pipelines/:id -- Get Only
/Users
/Users/:id -- Get Only
/Countries - List of Country Names for Addresses (Get Only)
/Currencies - List of Supported Currencies by Insightly (Get Only)
/Relationships - Get Only
/PipelineStages
/PipelineStages/:id - Get Only
/CustomFields
/CustomFields/:id - Get Only
For more details on the fields and records returned by the API, please see our preliminary documentation. We a building a developer website with more in-depth additional information which will be available soon, but this should get you started.
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.
