Introduction

This is an older version of the Insightly api. The latest version can be found here.

Overview

Users on all plans can use the REST-based Application Programming Interface (API) to query and update their Insightly data. Four HTTP verbs are supported: GET requests to retrieve information, POST to add new records, PUT to update records, and DELETE requests to remove records. The Resources sections below include detailed samples of Request bodies and Responses.

Resources

Resources such as Tasks, Contacts, Organisations, Opportunities, and Projects are accessible via the following URL: https://api.insight.ly/v2.1/{resource_name}. Supported data formats are JSON and XML.

The API also supports limited OData queries. Please see the Technical Details page for further information.

Limits

Requests that return over 10,000 records will exclude child objects such as addresses, phone numbers, and links. This is mostly applicable to large contact, organisation, or task lists. To retrieve the child objects, request each individual record from the server.

Authentication

Insightly uses HTTP Basic authentication in order to determine which user is making calls to the API. You will need an API key for each user to uniquely identify them when making calls to the API. Users' API key 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 will need to include your API key as the Base64-encoded user name, leave the password blank. Calls made to the API will assume this user's identity; permissions to view, edit and delete records via the API will be the same as those available to that user through the Insightly website.

Write/Update Requests

When creating and updating onjects via the API, it is important to use valid identifiers, for example when linking an organization to a contact, you must provide a valid CONTACT_ID and ORGANISATION_ID, which if you do not already have, you will need to look up. A good troubleshooting technique is to create objects and populate them with representative data via the Insightly web application, and then access them via the REST API to inspect their object graphs.

v2.2 API is Now Available

Check out version 2.2 of our API, which includes a number of significant improvements over v2.1, including:

  • Easy to use search endpoints which replace OData with a simple and easy to use query options.
  • Paginated results for large recordsets, great for users with lots of data
  • Improved documentation and an interactive web sandbox
  • Swagger based documentation and auto-generated client libraries
  • Support for incremental changes to existing objects (for example, add an address to a contact without uploading the entire object graph)

Visit api.insight.ly/v2.2/Help for information and documentation.

Subscribe To Our Developer Email List

Be sure to sign up for our developer email list to receive updates and service announcements about the API. You can subscribe at Insightly for Developers