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

Insightly CRM

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

This is a native InTouch YAML 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).