A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Insightly API is how an app or AI agent works with an Insightly CRM account: reading and updating contacts and organisations, qualifying leads, moving opportunities through a pipeline, and logging tasks, events, and notes against them. Access is granted through a per-user API key, and the key inherits exactly that user's access, so a call can reach only the records and fields that user can in the web app, with no separate per-endpoint scopes. Insightly does not push events, so an app learns about changes by reading records back, and it can ask for only those changed since a given time.
How an app or AI agent connects to Insightly determines what it can reach. There is one route, the REST API, and every call carries an API key that stands in for a single Insightly user, so an agent sees and changes exactly what that user can in the web app.
The REST API accepts and returns JSON, and pages through lists with skip and top parameters, at https://api.{pod}.insightly.com/v3.1, where {pod} is the account's region (for example na1). A call authenticates with the user's API key sent through HTTP Basic auth, with the key as the username and a blank password. There is no separate route for receiving events; an integration polls the API for changes.
Every call carries a single user's API key, found in that user's settings, sent through HTTP Basic auth with the key as the username and the password left blank. The key inherits exactly that user's access: a call can view, edit, and delete only the records and fields the user can in the web app, with no separate per-endpoint permissions. Operations that touch all users, like listing users, need an administrator's key. An administrator can switch API Access off for any user, after which their key is refused.
The Insightly API is split into the record types a sales team works with, like contacts, organisations, leads, opportunities, projects, and the tasks, events, and notes attached to them. Each has its own methods, and a write creates, edits, or removes a real record in the account.
Methods for working with people in the CRM.
Methods for working with companies and accounts.
Methods for working with unqualified prospects.
Methods for working with deals in a sales pipeline.
Methods for working with delivery projects.
Methods for working with the activity records attached to other objects.
Read-only methods for the pipelines and stages deals move through.
Read-only methods for users and the account's custom field definitions.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ContactsMethods for working with people in the CRM.6 | ||||||
| GET | /Contacts | Gets a list of Contacts, with optional filtering and paging. | read | — | Current | |
Reads whatever contacts the API key's user can see in the web app. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /Contacts/{id} | Gets a single Contact by its record id. | read | — | Current | |
Read-only; returns the record only if the user has access to it. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /Contacts/Search | Gets a filtered list of Contacts matching a field name and value. | read | — | Current | |
Read-only; searches within what the user can see. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Contacts | Adds a Contact to the CRM. | write | — | Current | |
Requires the user to have create permission on contacts. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Contacts | Updates an existing Contact; only the fields supplied are changed. | write | — | Current | |
An If-Match header carrying the record's ETag makes the update conditional. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /Contacts/{id} | Deletes a Contact by its record id. | write | — | Current | |
Permanent; requires the user to have delete permission on contacts. Acts onContact Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OrganisationsMethods for working with companies and accounts.4 | ||||||
| GET | /Organisations | Gets a list of Organisations (companies and accounts). | read | — | Current | |
Read-only; reads whatever organisations the user can see. Acts onOrganisation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Organisations | Adds an Organisation to the CRM. | write | — | Current | |
Requires create permission on organisations. Acts onOrganisation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Organisations | Updates an existing Organisation; only supplied fields change. | write | — | Current | |
Supports conditional update through the If-Match ETag header. Acts onOrganisation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /Organisations/{id} | Deletes an Organisation by its record id. | write | — | Current | |
Permanent; requires delete permission on organisations. Acts onOrganisation Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
LeadsMethods for working with unqualified prospects.4 | ||||||
| GET | /Leads | Gets a list of Leads (unqualified prospects). | read | — | Current | |
Read-only; reads whatever leads the user can see. Acts onLead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Leads | Adds a Lead to the CRM. | write | — | Current | |
Requires create permission on leads. Acts onLead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Leads | Updates an existing Lead; only supplied fields change. | write | — | Current | |
Supports conditional update through the If-Match ETag header. Acts onLead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /Leads/{id} | Deletes a Lead by its record id. | write | — | Current | |
Permanent; requires delete permission on leads. Acts onLead Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
OpportunitiesMethods for working with deals in a sales pipeline.5 | ||||||
| GET | /Opportunities | Gets a list of Opportunities (deals). | read | — | Current | |
Read-only; reads whatever opportunities the user can see. Acts onOpportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Opportunities | Adds an Opportunity to a pipeline. | write | — | Current | |
Requires create permission on opportunities. Acts onOpportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Opportunities | Updates an existing Opportunity; only supplied fields change. | write | — | Current | |
Supports conditional update through the If-Match ETag header. Acts onOpportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Opportunities/{id}/StateChange | Updates an Opportunity's state, like marking a deal won, lost, or abandoned. | write | — | Current | |
Changes the deal's outcome, not just its fields. Acts onOpportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /Opportunities/{id} | Deletes an Opportunity by its record id. | write | — | Current | |
Permanent; requires delete permission on opportunities. Acts onOpportunity Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ProjectsMethods for working with delivery projects.3 | ||||||
| GET | /Projects | Gets a list of Projects. | read | — | Current | |
Read-only; reads whatever projects the user can see. Acts onProject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Projects | Adds a Project to the account. | write | — | Current | |
Requires create permission on projects. Acts onProject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Projects | Updates an existing Project; only supplied fields change. | write | — | Current | |
Supports conditional update through the If-Match ETag header. Acts onProject Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Tasks, Events & NotesMethods for working with the activity records attached to other objects.8 | ||||||
| GET | /Tasks | Gets a list of Tasks. | read | — | Current | |
Read-only; reads whatever tasks the user can see. Acts onTask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Tasks | Adds a Task, optionally linked to another record. | write | — | Current | |
Requires create permission on tasks. Acts onTask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Tasks | Updates an existing Task; only supplied fields change. | write | — | Current | |
Supports conditional update through the If-Match ETag header. Acts onTask Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /Events | Gets a list of Events (calendar events and meetings). | read | — | Current | |
Read-only; reads whatever events the user can see. Acts onEvent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /Events | Adds an Event to the calendar. | write | — | Current | |
Requires create permission on events. Acts onEvent Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /Notes | Gets a list of Notes. | read | — | Current | |
Read-only; reads whatever notes the user can see. Acts onNote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /Notes | Updates an existing Note; only supplied fields change. | write | — | Current | |
Notes attach to a parent record like a contact or opportunity. Acts onNote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /Notes/{id} | Deletes a Note by its record id. | write | — | Current | |
Permanent; requires delete permission on notes. Acts onNote Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PipelinesRead-only methods for the pipelines and stages deals move through.2 | ||||||
| GET | /Pipelines | Gets a list of Pipelines configured in the account. | read | — | Current | |
Read-only; pipelines are configured in the Insightly settings, not via the API. Acts onPipeline Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /PipelineStages | Gets a list of Pipeline Stages, the steps a deal or project moves through. | read | — | Current | |
Read-only. Acts onPipelineStage Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Users & Custom FieldsRead-only methods for users and the account's custom field definitions.3 | ||||||
| GET | /Users | Gets a list of Users in the account. | read | — | Current | |
Returns user records; listing all users typically needs an administrator's API key. Acts onUser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /Users/Me | Gets the User object for the calling user, the identity behind the API key. | read | — | Current | |
Read-only; identifies whose access the key carries. Acts onUser Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /CustomFields/{objectName} | Gets the list of Custom Fields defined for a given object, like Contact or Opportunity. | read | — | Current | |
Read-only; reveals the account's custom field configuration for that record type. Acts onCustomField Permission (capability)None required VersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Insightly does not push events. An app or AI agent learns about changes by calling the API and reading the records back, rather than by receiving a notification when something changes.
| Event | What it signals | Triggered by |
|---|
Insightly limits how fast and how much an app can call, by a per-second ceiling that applies to every plan and by a separate daily allowance that depends on the account's plan.
Insightly applies two limits. A per-second ceiling of 10 requests applies to every plan. A separate daily allowance depends on the account's plan, starting at 1,000 requests per day on the free (Gratis) tier and rising to 40,000 (Plus), 60,000 (Professional), and 100,000 (Enterprise); the daily count expires on a rolling 24-hour window. Going over either limit returns HTTP 429, and every response carries X-RateLimit-Limit (the daily allowance) and X-RateLimit-Remaining (how much is left) so an integration can pace itself.
List endpoints page with skip and top query parameters, where top sets the page size (default 100, maximum 500) and skip sets the offset. A brief=true parameter returns a lighter version of each record, and an updated_after_utc parameter limits results to records changed since a given time, which suits incremental syncing.
A list request returns at most 500 records per page. Request and response bodies are JSON only, and GZIP or DEFLATE compression can be requested through the Accept-Encoding header. Dates in object data are UTC, formatted yyyy-MM-dd HH:mm:ss.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | Bad Request | The request was malformed or a field value was invalid, for example a missing required field or a value of the wrong type. | Fix the request body or parameters and resend. |
| 401 | Unauthorized | Authentication failed, most often because the API key was not Base64-encoded correctly for HTTP Basic auth, or API Access is disabled for the user. | Check the key is sent as the Basic auth username with a blank password, and confirm the user still has API Access. |
| 404 | Not Found | The requested record does not exist, or is not visible to the user the key belongs to. | Verify the record id and that the user has access to it. |
| 412 | Precondition Failed | A conditional update failed: the If-Match ETag sent with a PUT did not match the record's current ETag, meaning the record changed since it was read. | Re-read the record to get its current ETag, then retry the update with the new If-Match value. |
| 429 | Too Many Requests | A rate limit was hit, either the per-second ceiling or the account's daily allowance. | Slow the request rate, check the X-RateLimit-Remaining header, and retry after the limit window resets. |
Insightly versions its API with a number in the path, and v3.1 is the current version, adding products, price books, and quotes on top of the records earlier versions already exposed.
The current Insightly API version, with the version number carried in the request path. It adds endpoints for products, price books, and quotes (and their subcollections), calculated custom fields, ETag-based concurrency through If-Match, and the ability to update a record together with its subcollections in a single POST or PUT, where a PUT no longer requires all fields.
The previous version of the REST API, still available. It exposes the core CRM records, contacts, organisations, leads, opportunities, projects, tasks, events, and notes, but lacks the products, price books, and quotes added in v3.1 and the calculated custom fields.
The older v2.1, v2.2, and v2.3 line of the API, still reachable but superseded. New integrations should build against v3.1.
Build against v3.1; older versions stay available but lack the newer record types.
Insightly API version notes ↗Bollard AI sits between a team's AI agents and Insightly. Grant each agent exactly the access it needs, read or write, record type by record type, and every call is checked and logged.