Welcome to Version 3.1 of the Insightly API! Using our API, you can integrate Insightly with external systems and applications. In version 3.1, there are new endpoints for accessing Price Books, Products and Quotes, as well as support for calculated custom fields. The POST/PUT requests now accept subcollections in their payload to update the object as well as its subcollection in a single call. Version 3.1, like the previous version, uses HTTPS to access data within the Insightly web application. PUT requests do not require all fields to update records.

For development purposes, please review all API documentation to determine which version to use. The section Older API Versions contains links to the previous versions of the API. Please ensure that you are using the latest version of the API in order to have access to all the data in the Insightly web application.

What's Changed in Version 3.1?

3.1 additions and changes include:

• Endpoints for Products, Price Books and Quotes along with their subcollections like Price Book entries, Quote products and Opportunity products. With these endpoints, you can retrieve, add, delete and update records for these objects.The Guide to Products, Price Books, and Quotes explains these objects in more detail. You can use these endpoints if you have enabled the latest version of Insightly for your web instance. You can use the https://api.{pod}.insightly.com/v3.1/Instance endpoint to check if your instance is on the latest version.
• PUT requests don't require all fields to update records. Records can now be updated with the record ID field and the fields you want to set or edit. The record information is not replaced or updated unless a PUT request is used for specific fields that are set to change. To remove the value of a field that’s already set, use NULL.
• Tags, dates and email domains can now be updated in bulk from the parent entity's PUT/POST requests or the specific PUT endpoint for tags, email domains and dates.

You can sign up to receive updates and service announcements about our API and developer tools at Insightly for Developers

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
• DELETE requests to remove records.

API URL

The API is accessible via the following URL:https://api.{pod}.insightly.com/v3.1/

Your instances pod can be determined by accessing ‘User Settings’ and finding the API URL right under your API Key in the API Section. Finding your API URL explains where to find the API URL in the Insightly web application.

For example: If your Pod is ‘na1’ then your API’s URL would look like this: https://api.na1.insightly.com/v3.1/

Objects

Objects, such as Organisations or Projects, are accessible via the following URL: https://api.{pod}.insightly.com/v3.1/{resource_name}. Accessing the main endpoint for each object retrieves a list. For example, the following endpoint retrieves a list of Contacts:

https://api.{pod}.insightly.com/v3.1/Contacts

The ID of each record is an integer and it's used to reference individual records for retrievals, updates and deletes. For example, if you want to retrieve a project with the ID 123456:

https://api.{pod}.insightly.com/v3.1/Projects/123456

Detailed information about each endpoint is below. Read the documentation for each endpoint's response/request schema to understand the properties of each object and their functionality. Click RESPONSE SCHEMA or BODY SCHEMA to the right of each endpoint.

Limiting Returned Records

Similar to the previous version (version 3.0), this version returns paginated recordsets, with 100 records per response (default) and a maximum of 500 records per response.

To page through the recordset, use the top and skip query string parameters to specify the number of records to return and the starting record position.

Authentication

Insightly uses HTTP Basic authentication to determine which user is making calls to the API. Each user needs an API key, so the API can identify that user. Finding or resetting your API key explains where to find the API key in the Insightly web application.

The API key needs to be included as the Base64-encoded username, leaving the password blank. Calls made to the API assume that user's identity. Therefore, permissions to view, edit, and delete records via the API are the same as that user’s permissions on the Insightly web application.

If you are testing the API via the sandbox, you can paste your API key directly (without Base64 encoding) into the API key field on the left side of the page.

Write/Update Requests

When creating and updating objects through the API, it is important to use valid identifiers. For example, when updating the custom field on a Contact or Organization record, you must provide the custom FIELD_NAME (if you do not know the names, you will need to look them up via https://api.{pod}.insightly.com/v3.1/CustomFields). To troubleshoot, create objects and populate them with data through the Insightly web application. Then, access them via the REST API and inspect the data.

If you need to link multiple records to another record or update the links between records, it is important to use valid identifiers and the correct endpoints. For example, when linking an Organization to a Contact, you must provide a valid CONTACT_ID and ORGANISATION_ID. If you do not already have the IDs, look them up. To add or update the links for a contact, use the Adds a Link or Updates a Link contact endpoints.

Custom Fields

Custom fields are handled using the POST and PUT requests to the endpoint of each object. For example, to update the custom fields for a Contact record, use the Updates a Contact endpoint. To add a custom field, create a new contact, use the Adds a Contact endpoint and include the custom fields in the body. The newly created Contact will include the custom fields. When adding and updating custom fields, the FIELD_NAME is the unique identifier. To remove the value of a custom field, use NULL.

Use UTC time and dates for DATE and DATETIME custom fields. The UTC format needs to be used in POST and PUT request payloads. The API GET responses uses UTC dates and time.

Troubleshooting Tips

• Be sure you Base64 encode your API key for use in the Authorization header. If you don't do this, you may see a 401 authentication error. The Example API Call section shows what the Base64 encoded API looks like.

  Note: You do not need to Base64 encode the API key when using the Sandbox on this help page.

• Use Postman. It makes troubleshooting REST API integrations simple.
• When doing POST (create) and PUT (update) operations, start by getting an existing object via a GET request and make small edits to it. Review each object's endpoints to understand how to get the data and make changes to the records. For example, to get the links for a contact, use the Gets a Contact's Links endpoint.
• When linking Insightly objects, you'll need to have their unique identifiers. To find the unique identifier for a record, use a GET request. For example, a contact uses the CONTACT_ID field as the identifier.
• When updating an object’s subcollections, check to see if there is an endpoint for that subcollection. For example, to update an organization’s list of email domains, you can also use the Update Email Domains endpoints.
• To view more details about an object's properties, click to expand the RESPONSE SCHEMA or BODY SCHEMA sections on the right side of the endpoint definitions.
• Please note that the Quote endpoints use "Quotation" as the object name. Quote will not be accepted as a valid object name.
• File attachment endpoints do not return files that are associated with an email.

Older API Versions

The older API versions function differently than version 3.1. Versions 3.0 and below don't have endpoints for newer features like Price Books, Products and Quotes or new calculated custom fields. Versions 2.3 and below don’t have endpoints for Custom Objects. Versions 2.2 and below don't support all custom field types.

Before using an older version of the API, review the documentation to understand the limitations and endpoints.

To find the previous versions:

• Version 3.0 of the API at api.insight.ly/v3.0/Help
• Version 2.3 of the API at api.insight.ly/v2.3/Help
• Version 2.2 of the API at api.insight.ly/v2.2/Help
• Version 2.1 of the API at api.insight.ly/v2.1/Help

HTTP Compression

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

Supported Content Types

We only support application/json as content-type or accept headers. On GET requests, no content-type or accept header is necessary.

Example API Call

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

                            GET: https://api.{pod}.insightly.com/v3.1/Contacts
                            Authorization: Basic YWM5YTIyOTItZjI1YS00NDgzLTlkNTQtMDAwMDAwMDAwMDAw
                            Accept-Encoding: gzip

Rate Limiting / Throttling Requests

To prevent abuse of the API, the number of requests are limited on a per-instance basis. No more than 10 requests are allowed per second, and a daily limit is set based on the plan level, starting from 1000 requests per day for a Gratis plan. The daily limits have a rolling expiration of 24 hours. If you exceed the limits, the API responds with Http Status Code 429. The plan specific per day request quotas are below:

• Free/Gratis - 1,000 requests/day/instance
• Legacy plans - 20,000 requests/day/instance
• Plus - 40,000 requests/day/instance
• Professional - 60,000 requests/day/instance
• Enterprise - 100,000 requests/day/instance

Rate Limit Response Header

Each Web API request returns the following header information regarding rate limits and number of requests left. You will have a specific number of allowed requests per day. Once this threshold has been reached, we will return a status code 429 response.

Example Response

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999

When Limit is Reached

You will no longer be able to make requests against that endpoint until next day.

Example Response

HTTP/1.1 429 TOO MANY REQUESTS 
Content-Type: application/json
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0

Searching and Filtering

The Insightly API Version 3.1 offers flexible searching and filtering options for the Search endpoints to enable you to perform targeted searches. You can search by any standard or custom field of an entity.

To find a contact with a specific custom field value, you can use {field_name, field_value} parameters on the GET request:

https://api.{pod}.insightly.com/v3.1/Contacts/Search?field_name={custom field id}&field_value={value}

To find a lead (or leads) with a lead rating value of 5

https://api.{pod}.insightly.com/v3.1/Leads/Search?field_name=LEAD_RATING&field_value=5

In addition to these searching options, two query string parameters on GET requests give you paging options:

To specify a 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 the following GET request:

https://api.{pod}.insightly.com/v3.1/Contacts?top=20

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

https://api.{pod}.insightly.com/v3.1/Contacts?skip=50&top=20

These paging parameters also work for Search endpoints. To get top 10 Opportunities with 100% probability:

https://api.{pod}.insightly.com/v3.1/Opportunities/Search?field_name=PROBABILITY&field_value=100&top=10

Add the count_total=True parameter to get the total number of records returned in a response header called X-Total-Count:

https://api.{pod}.insightly.com/v3.1/Opportunities/Search?field_name=PROBABILITY&field_value=100&top=10&count_total=True

Date Formatting

The preferred date format for a date parameter in a URL is ISO 8601 date format. yyyy-mm-ddThh:mm:ssZ For example, 2018-04-09T16:58:14Z. You can format a date via Javascript's toJSON() method of the Date object. So an example URL would be:

https://api.{pod}.insightly.com/v3.1/Contacts/Search?updated_after_utc=2018-04-09T16:58:14Z

By contrast, the preferred date format for object data is yyyy-MM-dd HH:mm:ss. (Note that military time is used here instead of AM/PM.) For example, a task's REMINDER_DATE_UTC could be 2015-04-10 21:15:00.

For support, please visit our knowledge base and online community at support.insight.ly