Create and update contacts, organisations, and opportunities in Insightly via its REST API v3.1.

Provided free and as is, without warranty of any kind — including merchantability, fitness for a particular purpose, and the accuracy or completeness of any result. See the licence. You are responsible for checking what this produces before relying on it.

Insightly CRM

Create and update contacts, organisations, and opportunities in Insightly via its REST API v3.1.

This is a native InTouch IML tool — standard-library Python only (no pip dependencies), runs deterministically as a task in any job.

What it does

Branches on an operation and calls the matching Insightly v3.1 endpoint. It never raises on a non-2xx HTTP response: the HTTP status and the raw response result body are always returned so the caller (or assistant) can inspect the outcome. A transport-level failure (DNS/refused/timeout) fails the step.

Operations

operation	Method & path	Required inputs	Optional inputs
`list_contacts`	`GET /Contacts`	—	`top`, `skip`
`create_contact`	`POST /Contacts`	`firstName` or `lastName`	`emailAddress`, `phone`, `title`
`update_contact`	`PUT /Contacts`	`contactId`	`firstName`, `lastName`, `emailAddress`, `phone`, `title`
`create_organisation`	`POST /Organisations`	`organisationName`	`phone`
`create_opportunity`	`POST /Opportunities`	`opportunityName`	`opportunityState`, `bidAmount`

Field names map directly to Insightly's JSON schema: FIRST_NAME, LAST_NAME, EMAIL_ADDRESS, PHONE, TITLE, CONTACT_ID, ORGANISATION_NAME, OPPORTUNITY_NAME, OPPORTUNITY_STATE, BID_AMOUNT.

update_contact sends PUT /Contacts with CONTACT_ID in the body — that is how Insightly identifies the record to change.

API key setup

Sign in to the Insightly web app.
Open User Settings > API.
Copy your API key. The same page shows your API URL, e.g. https://api.na1.insightly.com/v3.1 — the na1 part is your pod.
Pass the key as apiKey and (if your pod is not na1) the pod as pod.

Authentication

Insightly uses HTTP Basic auth with the API key as the Base64-encoded username and a blank password. This tool builds the header for you:

Authorization: Basic base64(apiKey + ":")

Only the single API key is needed — no OAuth, no secret pair.

Examples

List the first 10 contacts:

{ "apiKey": "YOUR_KEY", "pod": "na1", "operation": "list_contacts", "top": "10" }

Create a contact:

{
  "apiKey": "YOUR_KEY",
  "operation": "create_contact",
  "firstName": "Ada",
  "lastName": "Lovelace",
  "emailAddress": "[email protected]",
  "title": "Analyst"
}

Update a contact's title (CONTACT_ID 12345):

{
  "apiKey": "YOUR_KEY",
  "operation": "update_contact",
  "contactId": "12345",
  "title": "Lead Analyst"
}

Create an organisation:

{ "apiKey": "YOUR_KEY", "operation": "create_organisation", "organisationName": "Acme Corp", "phone": "+1-555-0100" }

Create an opportunity:

{
  "apiKey": "YOUR_KEY",
  "operation": "create_opportunity",
  "opportunityName": "Acme — Q3 Renewal",
  "opportunityState": "OPEN",
  "bidAmount": "25000"
}

Output

field	description
`result`	Raw Insightly response body (JSON string). The created/updated record on writes, an array of contacts on `list_contacts`.
`status`	HTTP status code as a string (`200`/`201` on success; `400`/`401`/`404` etc. on error, with details in `result`).

Grounding

Built against the official reference at https://api.insightly.com/v3.1/Help (base URL, Basic-auth scheme, application/json content type, and the Contacts / Organisations / Opportunities endpoints).

Publishes

The keys a later task may reference as {{taskName.key}}. Referencing anything not listed here resolves to nothing at run time.

error
result
status

Input Properties

Every property this tool accepts, from its own tool.iml.

Property	Type	Required	Default	Description
`apiKey`	string	yes	—	DEPRECATED — bind an API Key credential to the task with `credentialName` instead. A key pasted here is stored in the workflow definition in clear and appears in every export of it. Still honoured for workflows built before the change.
`operation`	string	yes	—	One of: list_contacts, create_contact, update_contact, create_organisation, create_opportunity
`pod`	string	no	—	Insightly instance pod identifier from your API URL (e.g. na1, eu1). Defaults to na1 when empty.
`firstName`	string	no	—	Contact first name (FIRST_NAME) for create_contact/update_contact.
`lastName`	string	no	—	Contact last name (LAST_NAME) for create_contact/update_contact.
`emailAddress`	string	no	—	Contact email (EMAIL_ADDRESS) for create_contact/update_contact.
`phone`	string	no	—	Phone number (PHONE) for create_contact/update_contact or create_organisation.
`title`	string	no	—	Contact job title (TITLE) for create_contact/update_contact.
`contactId`	string	no	—	CONTACT_ID of the record to change. Required for update_contact.
`organisationName`	string	no	—	Organisation name (ORGANISATION_NAME). Required for create_organisation.
`opportunityName`	string	no	—	Opportunity name (OPPORTUNITY_NAME). Required for create_opportunity.
`opportunityState`	string	no	—	Opportunity state (OPPORTUNITY_STATE): OPEN, WON, LOST, SUSPENDED, ABANDONED. Defaults to OPEN when empty.
`bidAmount`	string	no	—	Opportunity value (BID_AMOUNT) for create_opportunity. Numeric.
`top`	string	no	—	Max records to return for list_contacts (1-500). Defaults to 20 when empty.
`skip`	string	no	—	Records to skip for list_contacts paging. Defaults to 0 when empty.