---
name: sales-insightly
description: "Insightly (insightly.com) platform help — unified CRM + project management + marketing + service platform whose differentiator is converting a won opportunity into a delivery Project. REST API v3.1 (pod-specific base https://api.{pod}.insightly.com/v3.1, HTTP Basic auth with a Base64-encoded API key as username, top/skip/count_total pagination, 10 req/sec + plan-gated daily quota 1k-100k, 429s, ETag/If-Match concurrency) plus workflow-automation webhooks (Professional+). Use when an Insightly API call returns 401 because the API key wasn't Base64-encoded, finding your pod/region for the base URL, hitting the daily request cap, syncing contacts/organisations/opportunities into a warehouse or another CRM, a webhook only fires from a workflow rule, working around limited reporting or no email sequencing, custom objects locked to Enterprise, or choosing Plus vs Professional vs Enterprise. Do NOT use for comparing CRMs across vendors (use /sales-crm-selection) or generic iPaaS wiring (use /sales-integration)."
argument-hint: "[describe what you need help with in Insightly]"
license: MIT
version: 1.0.0
tags: [sales, crm, platform]
github: "https://github.com/Insightly"
---

# Insightly Platform Help

## Step 1 — Gather context

If `references/learnings.md` exists, read it first for accumulated platform knowledge.

1. **What are you trying to do?**
   - A) Build an API integration — read/write contacts, organisations, opportunities, leads, projects, tasks
   - B) Set up a webhook to push CRM changes into a warehouse/CRM/Slack
   - C) Fix an auth (401) or pod/base-URL problem
   - D) Fix a daily rate-limit (429) problem
   - E) Work with custom fields / custom objects
   - F) Pick or understand a plan — Plus vs Professional vs Enterprise (CRM, Marketing, Service, AppConnect)

2. **Which module?** Sales CRM, Marketing (email automation/scoring), Service (tickets/portals), or AppConnect (the no-code iPaaS). They are licensed and priced separately.

3. **Auth:** Single internal account/script → **API key** (Base64-encoded as the Basic-auth username). You must know your **pod** (e.g. `na1`, `eu1`) — it's printed under the API key in User Settings and sets the base URL.

Skip-ahead rule: if the user's prompt already provides enough context, skip to Step 2.

## Step 2 — Route or answer directly

| If the question is about... | Route to... |
|---|---|
| CRM selection/comparison or migration strategy across vendors | `/sales-crm-selection {question}` |
| CRM data cleanup, dedupe, record matching | `/sales-data-hygiene {question}` |
| Contact/company enrichment for CRM records | `/sales-enrich {question}` |
| Outbound sequence / cadence design across platforms (Insightly has no native sequencing) | `/sales-cadence {question}` |
| Connecting Insightly to other tools generically (iPaaS) beyond AppConnect | `/sales-integration {question}` |
| Lead scoring model design | `/sales-lead-score {question}` |

When routing, give the exact command, e.g. "This is a CRM-comparison question — run: `/sales-crm-selection should I move from Insightly to HubSpot at 30 people`".

## Step 3 — Insightly platform reference

**Read `references/platform-guide.md`** for the full reference — the module map (CRM/Marketing/Service/AppConnect and what's API- vs webhook- vs UI-only), the project-linked-to-opportunity data model, pricing/plan gates, the data model with JSON shapes, and quick-start recipes (create a contact + opportunity; nightly incremental export with `count_total`; fire a webhook from a workflow rule).

**Read `references/insightly-api-reference.md`** for the integration surface — pod-specific base URL, the Base64 Basic-auth scheme, `top`/`skip`/`count_total` pagination, the resource list (Contacts, Organisations, Opportunities, Leads, Projects, Tasks, Events, Notes, Pipelines/PipelineStages, Tags, Products/Pricebooks/Quotes, Users, CustomFields), the `CUSTOMFIELDS` array shape, ETag/`If-Match` concurrency, the plan-gated daily quota + `X-RateLimit-*` headers, and the workflow-automation webhook payload/retry rules.

Answer using only the relevant section. Don't dump the full reference.

## Step 4 — Actionable guidance

Focus on the user's specific situation:

- **Base64-encode the API key.** Auth is HTTP Basic with the API key as the **username** and a **blank password** — and the key must be **Base64-encoded** in the `Authorization` header. Forgetting the encoding is the #1 cause of `401`. (The in-browser API sandbox doesn't require manual encoding, which trips people up.)
- **Get the pod right.** The base URL is `https://api.{pod}.insightly.com/v3.1` — the pod (`na1`, `eu1`, etc.) is printed under your API key in User Settings. A wrong pod looks like an auth/DNS failure.
- **Paginate with `top`/`skip`; count with `count_total`.** `top` defaults to 100, max 500; page with `skip`. Add `count_total=true` to get the total in the `X-Total-Count` header (it's an extra cost, so don't send it on every page).
- **Budget the daily quota.** The limit is per-day by plan (~1,000 free/legacy → 40,000 Plus → 60,000 Professional → 100,000 Enterprise) plus a 10 req/sec ceiling; `429` when exhausted. Pull incrementally on `DATE_UPDATED_UTC`, not full scans.
- **Webhooks come from workflow automation, not a subscription API.** You add a "Webhook" action to a workflow rule (workflow automation is **Professional+**); it POSTs the record's fields and **retries only twice** before giving up. Make the receiver ACK fast.
- **Custom objects are Enterprise-only.** Custom *fields* exist on lower tiers, but custom *objects*, products/pricebooks/quotes, and sandboxes are gated to Enterprise — check the tier before designing a model around them.

If you discover a gotcha, workaround, or tip not covered in `references/learnings.md`, append it there.

## Gotchas

> *Best-effort from research (2026-06) — review these, especially pricing and plan-gated features, which change.*

1. **The API key must be Base64-encoded** as the Basic-auth username (blank password). Un-encoded keys return `401`. The help-page sandbox hides this because it encodes for you.
2. **Base URL is pod-specific** (`https://api.{pod}.insightly.com/v3.1`). Hard-coding `na1` breaks EU/other-region accounts.
3. **Daily rate limit, not per-second-only.** You get a per-day quota by plan (free ~1,000 → Enterprise ~100,000) and a 10 req/sec ceiling; exhausting the day returns `429` until reset.
4. **Webhooks are a workflow action and retry only twice.** They require workflow automation (Professional+), fire on record add/update, and stop after two failed retries — a brief outage drops events silently.
5. **No email sequencing on any plan.** Surprising at this price; use a dedicated cadence tool for outbound.
6. **Built-in reporting is limited.** Multi-object/cross-object reporting is hard; teams often export to a warehouse or BI tool via the API.
7. **British spelling: `Organisations`** (not `Organizations`) in API paths and field names.
8. **Custom objects, products/pricebooks/quotes, and sandboxes are Enterprise-only.** Custom fields are available lower down.

## Related skills

- `/sales-crm-selection` — CRM comparison, selection, and migration strategy across vendors (is Insightly the right CRM, or time to switch?)
- `/sales-data-hygiene` — CRM data quality: dedupe, record matching, enrichment automation
- `/sales-enrich` — Contact/company enrichment for Insightly records
- `/sales-cadence` — Outbound sequence/cadence design across platforms (Insightly has no native sequencing)
- `/sales-integration` — Connecting Insightly to other tools via webhooks/Zapier/Make beyond AppConnect
- `/sales-do` — Not sure which skill to use? The router matches any sales objective to the right skill. Install: `npx skills add sales-skills/sales --skill sales-do -a claude-code`

## Examples

### Example 1: My API key keeps returning 401 (developer/automation)
**User says**: "I'm calling `https://api.insightly.com/v3.1/Contacts` with my API key and getting 401 Unauthorized."
**Skill does**: Diagnoses two issues — (1) the key must be **Base64-encoded** and sent as the Basic-auth **username** with a blank password (`Authorization: Basic base64(apikey:)`), not passed raw; (2) the base URL must use your **pod** (`https://api.{pod}.insightly.com/v3.1`), found under the key in User Settings. Shows the working cURL + Python snippet from the API reference.
**Result**: Authenticated requests succeed against the correct regional endpoint.

### Example 2: Sync new opportunities into BigQuery nightly (developer/automation)
**User says**: "I want to pull opportunities that changed each night into our warehouse without blowing the rate limit."
**Skill does**: Recommends an incremental pull filtered on `DATE_UPDATED_UTC`, paginated with `top`/`skip`, using `count_total=true` only on the first page to size the job from `X-Total-Count`; watch `X-RateLimit-Remaining` and back off on `429`. Notes the daily quota scales by plan (Professional ~60k/day). Points to Recipe 2 in the platform guide.
**Result**: A bounded nightly export that stays under the daily quota.

### Example 3: Is Insightly the right CRM for us?
**User says**: "We're a 25-person agency outgrowing spreadsheets — is Insightly a good fit or should we look at HubSpot?"
**Skill does**: Recognizes a cross-tool selection question and routes: "run: `/sales-crm-selection 25-person agency, project-delivery work, Insightly vs HubSpot`." Briefly notes Insightly's edge for project-linked work (opportunity→project) and its weak spots (reporting, no sequencing) but defers the comparison to the strategy skill.
**Result**: User is handed to the right strategy skill with a ready prompt.

## Troubleshooting

### 401 Unauthorized on every call
**Symptom**: All requests fail with `401` even though the API key is correct.
**Cause**: The key wasn't **Base64-encoded** before being placed in the `Authorization: Basic` header, or it's being sent as a password instead of the username, or the request hit the wrong **pod**.
**Solution**: Encode the key as `base64("APIKEY:")` (key as username, empty password) and send `Authorization: Basic <encoded>`. Confirm the base URL uses your pod from User Settings (`https://api.{pod}.insightly.com/v3.1`). The browser sandbox auto-encodes, so a call that works there but not in your code is almost always the missing encoding.

### My webhook stopped firing
**Symptom**: A webhook delivered for a while, then events stopped arriving.
**Cause**: Insightly webhooks are **workflow-automation actions** (Professional+) and retry only **two** more times after a failed delivery, then give up for that event — a brief downstream outage silently drops events. They also only fire when the workflow rule's add/update conditions match.
**Solution**: Make the receiver return `2xx` immediately and process async; verify the workflow rule's trigger conditions still match the records you expect; for guaranteed catch-up, run a periodic reconciliation pull on `DATE_UPDATED_UTC`. Confirm you're on a plan that includes workflow automation.

### Hitting the daily rate limit (429)
**Symptom**: `429 Too Many Requests`, often later in the day or during a backfill.
**Cause**: The **per-day** request quota for your plan is exhausted (~1,000 free/legacy → 40,000 Plus → 60,000 Professional → 100,000 Enterprise), or you exceeded the 10 req/sec ceiling.
**Solution**: Switch full scans to incremental pulls on `DATE_UPDATED_UTC`, request larger pages (`top=500`), avoid `count_total` on every page, cache reference data (pipelines, custom-field metadata), throttle to under 10 req/sec, and watch `X-RateLimit-Remaining`. If still constrained, move to a higher plan with a larger daily quota.