Insightly API Essential Guide

What type of API does Insightly provide?

Based on the search results provided, Insightly has a REST API. Here are the key points:

Type of API

• Insightly uses a RESTful API

Key Features

• The API allows developers to create custom applications and system integrations with Insightly CRM
• It supports JSON-encoded object graphs in response to requests
• Four HTTP verbs are supported: GET, POST, PUT, DELETE
• The API can be used to query and update Insightly data

Authentication

• Uses HTTP Basic authentication
• Requires an API key for each user to identify them

Versioning

• The current version is 3.1
• Older versions (3.0, 2.3, 2.2, 2.1) are still available but have limitations

Additional Details

• Supports GZIP and DEFLATE compression
• Has rate limiting/throttling to prevent abuse
• Offers flexible searching and filtering options
• Supports custom fields

Best Practices

• Use UTC time and dates for DATE and DATETIME custom fields
• Review API documentation to determine which version to use
• Use Postman for troubleshooting REST API integrations

In summary, Insightly provides a comprehensive REST API that allows developers to integrate Insightly CRM functionality into their applications and systems.

Does the Insightly API have webhooks?

Webhooks

The official Insightly API documentation does not explicitly mention support for webhooks. The API appears to be primarily REST-based, supporting GET, POST, PUT, and DELETE operations.

Event Subscriptions

While webhooks are not mentioned, Insightly does support events via polling. This allows you to receive notifications about changes to Insightly data, but requires you to periodically check for updates rather than receiving real-time push notifications.

Types of Events

The polling mechanism allows you to subscribe to events for the following resources:

1. Contacts
2. Accounts (Organizations)
3. Leads
4. Opportunities

Event Configuration

To configure polling for events, you need to set up the following parameters:

• event.notification.enabled: Set to true to enable events
• event.vendor.type: Set to "polling"
• event.poller.refresh_interval: Specify the polling interval in minutes
• event.notification.callback.url: Provide a URL where you want to receive event notifications
• event.poller.configuration: Configure the specific resources you want to poll for changes

Event Data

For each resource, you can configure:

• The URL to query for updates
• The field used to uniquely identify the resource
• Date fields for tracking updates and creation of records

Best Practices

1. Use UTC time and dates for custom DATE and DATETIME fields.
2. When setting up polling, consider the balance between timely updates and API usage limits.
3. Implement proper error handling and retry logic in your event processing code.

While the Insightly API doesn't offer native webhook support, the polling mechanism provides a way to stay updated on changes to your Insightly data. If you require real-time updates, you may need to consider implementing a custom solution or using a third-party integration platform that offers webhook functionality for Insightly.

Rate Limits and other limitations

The Insightly API has the following rate limits:

General Rate Limit

• No more than 10 requests are allowed per second per instance [1][5].

Daily Rate Limits

The daily rate limits vary based on the plan level [1][5]:

• 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

Key Points to Consider

• The daily limits have a rolling expiration of 24 hours [5].
• If you exceed the limits, the API responds with HTTP Status Code 429 (Too Many Requests) [5].
• Each API request returns header information regarding rate limits and number of requests left [5].

Rate Limit Response Headers

The API returns the following headers with rate limit information [5]:

X-RateLimit-Limit: [daily limit]
X-RateLimit-Remaining: [remaining requests]

Best Practices

• Monitor the rate limit headers to track your usage.
• Implement exponential backoff and retry logic to handle rate limit errors.
• Spread out requests over time to avoid hitting the per-second limit.
• Consider caching frequently accessed data to reduce API calls.

By adhering to these rate limits and implementing proper handling, you can ensure smooth integration with the Insightly API while avoiding disruptions due to exceeding the allowed request quotas.

Latest API Version

Based on the search results provided, the most recent version of the Insightly API is version 3.1. Here are the key points:

1. The direct answer: The most recent version of the Insightly API is version 3.1.

2. Key points to consider:

• Version 3.1 introduces new endpoints for accessing Price Books, Products and Quotes, as well as support for calculated custom fields.

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

• Version 3.1 uses HTTPS to access data within the Insightly web application.

• PUT requests in version 3.1 do not require all fields to update records.

3. Best practices:

• Always use the latest version of the API to have access to all the data in the Insightly web application.

• Review the API documentation to determine which version to use for development purposes.

• Use UTC time and dates for DATE and DATETIME custom fields.

• When testing the API via the sandbox, you can paste your API key directly (without Base64 encoding) into the API key field.

It's important to note that older API versions (3.0 and below) function differently and may not have endpoints for newer features like Price Books, Products, and Quotes, or support for new calculated custom fields.

How to get a Insightly developer account and API Keys?

To get a developer account for Insightly to create an API integration, here are the key steps:

1. Sign up for an Insightly account

If you don't already have one, you'll need to sign up for an Insightly account. You can start with a free trial or paid plan.

2. Obtain your API key

Once you have an account:

1. Log in to your Insightly account
2. Go to User Settings
3. Find the API section
4. Your API key will be listed there

3. Get familiar with the API documentation

Insightly provides detailed API documentation at:

https://api.insightly.com/v3.1/Help

This includes information on:

• Authentication
• Available endpoints
• Request/response formats
• Code examples

4. Set up authentication

The Insightly API uses HTTP Basic authentication. You'll need to include your API key as the Base64-encoded username in the Authorization header of your requests, with a blank password.

5. Start making API calls

You can now start making API calls to integrate Insightly with your application. Some key points:

• The API base URL is: https://api.{pod}.insightly.com/v3.1/
• Replace {pod} with your instance's pod (e.g. na1)
• Use GET, POST, PUT, DELETE requests as needed
• JSON is the default response format

6. Test in the API sandbox

Insightly provides a web-based sandbox where you can test API calls. You can paste your API key directly here without Base64 encoding.

What can you do with the Insightly API?

Based on the search results provided, here is a list of data models that can be interacted with using the Insightly API, along with what is possible for each:

Contacts

• Create new contacts
• Retrieve contact information
• Update existing contacts
• Delete contacts

Leads

• Create new leads
• Update lead information
• Convert leads to opportunities or contacts
• Delete leads

Opportunities

• Create new opportunities
• Update opportunity details
• Close won/lost opportunities
• Delete opportunities

Tasks

• Create new tasks
• Assign tasks to users
• Update task status and details
• Delete tasks

Projects

• Create new projects
• Update project information
• Link projects to opportunities or contacts
• Delete projects

Organizations

• Create new organization records
• Update organization details
• Link organizations to contacts and opportunities
• Delete organizations

Custom Fields

• Create custom fields for various record types
• Update custom field values
• Retrieve custom field data

Users

• Retrieve user information
• Update user details
• Manage user permissions

Email

• Log emails against contact/lead records
• Retrieve email communication history

Notes

• Add notes to various record types
• Retrieve notes linked to records
• Update and delete notes

Events

• Create calendar events
• Update event details
• Link events to contacts/opportunities

Pipelines

• Retrieve pipeline information
• Update pipeline stages

Reports

• Generate custom reports using API data
• Retrieve report data

Key points to consider:

• The API follows REST conventions and uses JSON for data exchange
• Authentication is required using API keys
• Rate limits may apply to API requests
• The API allows for integration with other systems and applications
• Developers can use client libraries for Java, .NET and Python, or leverage Swagger for other languages

The Insightly API provides comprehensive access to most core CRM data models, enabling developers to build robust integrations and custom applications leveraging Insightly's CRM functionality.