Insightly integration

What it does

The Insightly integration lets you run CRM automations on behalf of any client whose Insightly account you manage. Connect an Insightly account once, then create, find, update and delete the records the business actually runs on — contacts, leads, organisations, opportunities, projects, tasks, events, notes, emails and tickets — move deals along a pipeline, attach notes, tags, links and files to any record, and start a workflow whenever a record is created or changed.

Connect an Insightly account

1. In Insightly, click the profile icon (top right) and open User Settings. Scroll to the API Key section and copy two things: the API key, and the API URL shown beside it — for example https://api.na1.insightly.com/v3.1.
2. In TaskJuice, add the connection from the Insightly node in your workflow, and fill three fields:
   • Insightly Pod — the region label from that API URL. api.na1.insightly.com means na1. The pods in service are na1 (North America), eu1 (Europe) and au1 (Asia-Pacific).
   • Insightly API Key — the key you copied.
   • Password — leave it blank. Insightly authenticates on the API key alone; it is sent as the HTTP Basic username and the password is ignored.

The connection is read- and write-capable across everything the key's user can see, because Insightly's API key carries that user's own permissions and has no scope model of its own. To narrow what an automation can reach, issue the key from an Insightly user with a restricted profile. Rotate or revoke it from the same User Settings -> API Key page at any time.

Triggers

Insightly's API publishes no webhooks, so every trigger here polls the provider's change feed (/{Object}/Search?updated_after_utc=) on the interval you choose. The first cycle after publishing establishes a watermark and emits nothing, so records that already existed are never replayed at you.

Every New-X trigger except New Email fires only for records created after the workflow is first published, judged by the record's own creation date, so editing an older record, or importing records that keep their original creation date, does not fire it. (A logged Insightly email carries no update timestamp, so New Email needs no such rule.)

Each trigger emits one activation per poll cycle, with every record observed in that cycle wrapped in an items array. Add a Loop node (type: array, arrayPath: items) downstream to handle each record on its own, or leave the Loop off to build a digest.

Two families, and the difference matters:

• New X fires once per record, ever. A record that changes again later does not re-fire it. Use it for "when a lead comes in, do this".
• Updated X fires again every time a record's contents change. Use it for "when a deal moves, sync it".

Both families cover contacts, leads, organisations, opportunities, projects, tasks, events, tickets and notes. New Email exists on its own — Insightly treats logged emails as an immutable record with no update timestamp, so there is no Updated Email to offer.

Actions

Records

Every primary record type has the same five verbs, so contact below stands in for lead, organisation, opportunity, project, task, event and ticket too:

• insightly/list-contacts. List one page of records, offset-paginated with skip/top (Insightly caps a page at 500).
• insightly/get-contact. Look up a single record by its Insightly ID.
• insightly/find-contacts. Find records by an exact field match (field_name + field_value), or by last-updated time.
• insightly/create-contact. Create a record. Owner, category, status, pipeline and organisation are dropdowns fed live from the connected account, not IDs to paste.
• insightly/update-contact. Update a record.
• insightly/delete-contact. Permanently delete a record. Irreversible.

Notes and emails differ where the provider does: notes have no top-level create (they are added to a parent record — see below), and emails are read-and-delete only.

Pipelines and deal state

• insightly/change-opportunity-pipeline / insightly/change-project-pipeline. Move a record onto a pipeline, optionally landing it on a specific stage.
• insightly/change-opportunity-stage / insightly/change-project-stage. Move a record to a different stage of its current pipeline.
• insightly/update-opportunity-state. Mark an opportunity Open, Won, Lost, Abandoned or Suspended, with an optional state reason.

Anything attached to a record

These take a record type dropdown plus a record ID, so one action covers every record type the provider supports it on:

• Notes — insightly/add-note-to-record, insightly/list-record-notes.
• Tags — insightly/add-tag-to-record, insightly/remove-tag-from-record, insightly/list-record-tags.
• Links between records — insightly/link-record, insightly/unlink-record, insightly/list-record-links.
• Files — insightly/upload-file-attachment (takes a file reference from an upstream step), insightly/list-record-file-attachments, insightly/get-file-attachment (a download link that expires after about ten minutes), insightly/download-file-attachment (returns a file reference you can upload elsewhere), insightly/delete-file-attachment.
• Following — insightly/follow-record, insightly/unfollow-record.

Lookups

Useful on their own, and the same endpoints that fill the dropdowns above: insightly/list-pipelines, insightly/list-pipeline-stages, insightly/list-lead-statuses, insightly/list-lead-sources, insightly/list-opportunity-categories, insightly/list-opportunity-state-reasons, insightly/list-project-categories, insightly/list-task-categories, insightly/list-file-categories, insightly/list-users, insightly/list-teams, insightly/list-currencies, insightly/list-countries, insightly/list-relationships, insightly/list-custom-fields, insightly/get-current-user and insightly/get-instance.

Working with custom fields

Every create and update action carries a Custom Fields input taking an array of { "FIELD_NAME": "...", "FIELD_VALUE": ... } objects. Run insightly/list-custom-fields against the record type first to discover the FIELD_NAME values your client's account actually defines — they are per-account, not global.

Known limitations

• No webhooks. Insightly's REST API has no subscription endpoints; the only outbound-webhook mechanism in the product is a step inside Insightly's own workflow automation, configured by hand and gated to higher plans. Every trigger here therefore polls, and the shortest interval is 60 seconds.
• Updates replace rather than patch. Insightly's update endpoint takes the whole record. Fields you leave empty are omitted from the request rather than sent blank, but a field the record holds that the action does not send may be cleared by the provider. Read the record first when you only mean to change one field.
• Rate limits scale with the plan — roughly 10 requests/second on Plus, 40 on Professional and 80 on Enterprise, each with a daily ceiling. A 429 is retried automatically.
• The pod is per-account. A connection is bound to one regional host; a client in a different region needs its own connection.
• The API key carries its user's permissions. There is no scope model, so a key issued from an administrator can reach everything that administrator can.
• Record photos and custom image fields are not available. Insightly uploads them as a raw application/octet-stream body, and this integration does not offer those uploads yet. File attachments, which the provider accepts as multipart/form-data, are fully supported.