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).
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.
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)
Which module? Sales CRM, Marketing (email automation/scoring), Service (tickets/portals), or AppConnect (the no-code iPaaS). They are licensed and priced separately.
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
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 ; fire a webhook from a workflow rule).
Read references/platform-guide.md
count_total
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.
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.
Base URL is pod-specific (https://api.{pod}.insightly.com/v3.1). Hard-coding na1 breaks EU/other-region accounts.
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.
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.
No email sequencing on any plan. Surprising at this price; use a dedicated cadence tool for outbound.
Built-in reporting is limited. Multi-object/cross-object reporting is hard; teams often export to a warehouse or BI tool via the API.
British spelling: Organisations (not Organizations) in API paths and field names.
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.
